AIO API — Pivot Report Endpoint

Endpoint: POST <https://app.aio.tech/api/v1/pivot-report/data?token=YOUR_API_TOKEN>

Возвращает сводный набор метрик, сгруппированный по одному или нескольким измерениям ("definitions"), отфильтрованный по произвольным условиям, с необязательными переключателями атрибуции и очистки. Ответ это вложенный объект, ключи которого представляют собой JSON‑кодированные селекторы групп, а внутри лежит карта placeholders: ID метрики → значение.

Быстрый старт

curl -X POST \\
  '<https://app.aio.tech/api/v1/pivot-report/data?token=XXXX>' \\
  -H 'Content-Type: application/json' \\
  -H 'Accept: application/json' \\
  -H 'x-tenant-id: 00000000-0000-0000-0000-000000000000' \\  # optional
  -d '{
    "dates": ["2025-08-18 00:00:00", "2025-08-24 23:59:59", "Asia/Bangkok"],
    "back_fix_attribution": false,
    "event_time_attribution": false,
    "hide_bots": true,
    "hide_empty_metrics": true,
    "hide_trash": true,
    "conditions": [],
    "definitions": [
      {"key": "campaign_owner_uuid"},
      {"key": "campaign_uuid"},
      {"key": "landing_uuids[1]"}
    ]
  }'

Аутентификация и Tenant

API-токен: передаётся как параметр строки запроса: ?token=YOUR_API_TOKEN.
Заголовок x-tenant-id (необязательно): UUID Tenant, по которому нужны данные. Используйте только если у вашего токена есть доступ к нескольким Tenant. Если заголовок не указан, данные берутся по текущему Tenant пользователя, которому принадлежит API-токен.

Общие заголовки

Content-Type: application/json
Accept: application/json
x-tenant-id: <tenant-uuid> (необязательно)

Схема тела запроса

{
  "dates": [
    "YYYY-MM-DD HH:mm:ss", // from (inclusive)
    "YYYY-MM-DD HH:mm:ss", // to (inclusive)
    "IANA/Timezone"        // e.g., "Europe/Berlin"
  ],
  "back_fix_attribution": false,
  "event_time_attribution": false,
  "hide_bots": true,
  "hide_empty_metrics": true,
  "hide_trash": true,
  "conditions": [
   { "key": "<filter_key>", "values": ["<uuid>", "<uuid>"] } 
   ],
  "definitions": [
   { "key": "<grouper_key>" }, ... 
   ]
}

По полям

Поле	Тип	Обязательное	Примечания
`dates`	array[3]	Yes	`[from, to, timezone]`. Строки даты и времени в формате `YYYY-MM-DD HH:mm:ss`. Третий элемент это часовой пояс IANA (например, `Asia/Bangkok`). Диапазон включает границы (для конца дня используйте `23:59:59`).
`back_fix_attribution`	boolean	Yes	Соответствует переключателю Backfix в таблицах AIO. true = показывать данные без backfix; false = применять логику backfix.
`event_time_attribution`	boolean	Yes	Соответствует Event Time Attribution в таблицах AIO. true = атрибутировать конверсии по времени конверсии; false = атрибутировать по визиту/времени исходного события.
`hide_bots`	boolean	Yes	true скрывает трафик ботов; false включает его.
`hide_empty_metrics`	boolean	Yes	Соответствует кнопке Traffic в таблицах AIO. true = показывать только метрики, у которых есть значения в метриках, помеченных как основные; false = показывать все значения всех метрик.
`hide_trash`	boolean	Yes	true скрывает трафик, помеченный как trash (например, отфильтрованный клоакой); false включает его.
`conditions`	array	Yes	Произвольные фильтры. Каждый элемент: `{ key, values[] }`. Ключи берутся из AIO API — каталог Fields & Groupers (см. ссылки ниже). Значения это UUID выбранных сущностей. Несколько `conditions` объединяются через AND.
`definitions`	array	Yes	Измерения группировки (от 1 до 7). Каждый элемент: `{ key }`. Ключи берутся из AIO API — каталог Fields & Groupers. Движок возвращает все комбинации по указанным группировкам.

Справочники ключей

AIO API — каталог Fields & Groupers: справочник допустимых значений conditions.key и definitions.key и ожидаемых типов UUID. AIO API — каталог Fields & Groupers.
Сопоставление метрик: в AIO → Settings → Metrics можно сопоставить metric_<uuid> с названиями и единицами измерения.

Индексированные ключи: некоторые измерения многозначные. Чтобы выбрать конкретную позицию, используйте квадратные скобки, например landing_uuids[1] ( здесь [1] выбирает первый лендинг ).

Формат ответа

Ответ это вложенный объект. На каждом уровне вложенности:

Ключ объекта это JSON‑кодированная строка, представляющая селектор группировки этого уровня, например "{\\"group_1\\":\\"2baf...\\"}".
Значение это объект, который может содержать:
- placeholders: карту ID метрик → числовые значения.
- filters: плоскую карту group_N → выбранные UUID на пути к этому узлу.
- Дальнейшие вложенные объекты для следующих групп (например, ключи вида "{\\"group_2\\":\\"...\\"}", затем group_3 и так далее).

Пример (сокращённый)

{
  "{\\"group_1\\":\\"2baf3631-8c8e-4f03-8753-d28d4808048c\\"}": {
    "placeholders": {
      "metric_8606f176-75c4-46bb-ba0d-5c23ae3f413c": 3671,
      "metric_0b45030f-ed3c-4559-a22c-bb45b73b4e16": 806,
      "metric_3c749b43-6e5c-45e1-9c50-ebe2ac00985e": 0.2601470989,
      "metric_a8658f92-9c2c-46ab-89a2-de05e7b5cbd2": 12.3
      // ...more metrics
    },
    "filters": { "group_1": "2baf3631-8c8e-4f03-8753-d28d4808048c" },
    "{\\"group_2\\":\\"004f8cac-e6d8-485f-928b-ff5b5d5ec214\\"}": {
      "{\\"group_3\\":\\"5732e6e8-b09b-4d34-9e78-2b56ec26afa0\\"}": {
        "placeholders": { /* metrics */ },
        "filters": {
          "group_1": "2baf...8048c",
          "group_2": "004f...c214",
          "group_3": "5732...afa0"
        }
      }
    }
  }
}

Интерпретация метрик

Ключи внутри placeholders это ID метрик (например, metric_8606f176-...).
Сопоставьте ID через AIO → Settings → Metrics (у каждой метрики указаны её UUID и название).

Почему ключи JSON‑кодированные?

Так порядок групп остаётся явным (group_1..group_N) и исключаются коллизии. Считайте каждый ключ верхнего уровня значением первой группировки и спускайтесь вглубь по следующим группам. Объект filters в любом узле повторяет полный путь (по одному ключу на каждый group_N).

Практические рецепты

1) Разворачивание ответа (PHP)

function walkPivot(array $node, array $path = []): \\Generator {
    foreach ($node as $k => $v) {
        if (str_starts_with($k, '{') && str_ends_with($k, '}')) {
            $sel = json_decode($k, true, 512, JSON_THROW_ON_ERROR); // [ 'group_1' => 'uuid' ]
            $nextPath = array_merge($path, $sel);
            yield from walkPivot($v, $nextPath);
        } elseif ($k === 'placeholders' && is_array($v)) {
            yield ['path' => $path, 'metrics' => $v];
        }
    }
}

3) Фильтрация по нескольким сущностям

"conditions": [
  { "key": "campaign_uuid", "values": ["<uuidA>", "<uuidB>"] },
  { "key": "campaign_owner_uuid", "values": ["<userUuid>"] }
]

4) Выбор группировок (1..7)

"definitions": [
  { "key": "campaign_owner_uuid" },
  { "key": "campaign_uuid" },
  { "key": "landing_uuids[1]" }
]

Движок возвращает все комбинации, присутствующие в данных по указанным группировкам (аналогично таблицам AIO). Порядок definitions определяет порядок вложенности (group_1, group_2, ...).

Переключатели поведения

Backfix (back_fix_attribution) Определяет, показываются ли данные с учётом backfix-визитов или без них.
- true → логика backfix не применяется.
- false → логика backfix применяется (рекомендуется для итоговых отчётов).
Event Time Attribution (event_time_attribution) Определяет, по какой временной метке конверсии попадают в диапазон дат.
- true → атрибуция по времени конверсии.
- false → атрибуция по времени визита.
Очистка трафика
- hide_bots: true → исключить трафик ботов.
- hide_trash: true → исключить trash-визиты и визиты, отсеянные клоакой.
- hide_empty_metrics: true → убирает из placeholders этого узла значения метрик, не помеченных как основные, и уменьшает размер ответа.

Полный пример

cURL (с несколькими условиями и 3 группировками)

curl -X POST '<https://app.aio.tech/api/v1/pivot-report/data?token=XXXX>' \\
  -H 'Content-Type: application/json' -H 'Accept: application/json' \\
  -d '{
    "dates": ["2025-08-18 00:00:00", "2025-08-24 23:59:59", "Europe/Berlin"],
    "back_fix_attribution": false,
    "event_time_attribution": true,
    "hide_bots": true,
    "hide_empty_metrics": true,
    "hide_trash": true,
    "conditions": [
      {"key":"campaign_uuid","values":["004f8cac-e6d8-485f-928b-ff5b5d5ec214"]},
      {"key":"campaign_owner_uuid","values":["2baf3631-8c8e-4f03-8753-d28d4808048c"]}
    ],
    "definitions": [
      {"key":"campaign_owner_uuid"},
      {"key":"campaign_uuid"},
      {"key":"landing_uuids[1]"}
    ]
  }'

Советы и ограничения

Количество definitions: от 1 до 7. Порядок важен (задаёт group_1..group_N).
Комбинаторный вывод: API возвращает каждую комбинацию, существующую в данных для выбранных группировок (аналогично таблицам AIO). Редкие комбинации могут отсутствовать.
UUID везде: в conditions.values и filters.group_N передаются UUID соответствующих сущностей. Расшифровывайте их через свой локальный кэш или справочники AIO.
Размер ответа: используйте hide_empty_metrics: true и минимальный набор definitions и conditions, чтобы уменьшить ответ.
Часовые пояса: всегда указывайте часовой пояс IANA, чтобы избежать неоднозначности.
Сопоставление метрик: в AIO → Settings → Metrics можно сопоставить ID metric_<uuid> с названиями и единицами измерения.

Ссылка на каталог полей

AIO API — каталог Fields & Groupers

FAQ

В: Как сопоставить metric_<uuid> с названием вроде Visits или CR?
О: Откройте AIO → Settings → Metrics и по перечисленным UUID сопоставьте значения из placeholders с понятными названиями метрик.

В: Можно ли получить плоские строки вместо вложенных объектов?
О: Используйте приведённые выше сниппеты разворачивания, чтобы обойти узлы и сформировать строки { group_1..N, metric_id, value }.

В: К какой временной метке применяется диапазон dates?
О: Зависит от event_time_attribution. При true это время конверсии, при false время визита