Сформировать отчет

Отправьте POST-запрос с нужными метриками, группировками, фильтрами и периодом. Будет поставлена асинхронная задача построения отчета или возвращена существующая taskId для ранее запрошенного аналогичного запроса.

В ответ возвращается taskId, по которому можно отслеживать готовность отчета.

POST /api/v2/reports

Характеристика	Значение
Метод	`POST`
Путь	`/api/v2/reports`
Заголовки	`Content-Type: application/json` (обязателен)
Успех	`202 Accepted`

Тело запроса

Поле	Тип	Обязательность	Описание
`metrics`	массив строк	Да, логически	Не пустой массив; каждый элемент — непустая строка. Значения `name` из `GET /metadata → metrics`.
`dimensions`	массив строк	Нет	Группировки. Значения `name` из `GET /metadata → dimensions`. Пустой массив или отсутствие поля трактуются как «без группировок».
`filters`	массив объектов	Нет	Фильтры. Структура описана ниже.
`dateRange`	объект	Да, логически	Период отчета. Поля `from` и `to` в формате `YYYY-MM-DD`.
`limit`	целое	Нет	Максимум строк результата; если указан, должен быть в интервале 1 — 1 000 000 включительно.
`ownerId`	целое > 0	Обязателен для рекламодателей	ID администратора аккаунта.

Структура `filters[]`

Поле	Тип	Описание
`field`	строка	Поле фильтра. Значение `field` из `GET /metadata → filters`.
`operator`	строка	Оператор сравнения (см. ниже таблицу «Допустимые значения `operator` в фильтрах»).
`value`	JSON	Обязательно, не `null`: для скалярных операторов — скаляр (строка / число / boolean); для `in`, `notIn`, `hasAny` — непустой массив скаляров одного типа.

Индексы в сообщениях об ошибках нумеруются с нуля: filters[0].field, …

Допустимые значения `operator`в фильтрах

Оператор	Описание
`eq`	Равно.
`ne`	Не равно.
`lt` / `le`	Меньше / меньше или равно.
`gt` / `ge`	Больше / больше или равно.
`like` / `notLike`	Соответствует / не соответствует шаблону.
`in`	Входит в список значений.
`notIn`	Не входит в список значений.
`hasAny`	Пересекается с множеством.

Объект `dateRange`

Поле	Тип	Описание
`from`	string	Обязательно, не пусто: дата `YYYY-MM-DD` (календарная).
`to`	string	Должно выполняться `from ≤ to`.

Число календарных дней в интервале включительно не должно превышать maxDateRangeDays из метаданных (365).

Пример запроса

curl -X POST \
  -H 'Authorization: OAuth <токен>' \
  -H 'Content-Type: application/json' \
  -d '{
    "metrics": ["loads_commercial", "clicks_total", "ctr"],
    "dimensions": ["date", "campaign_id"],
    "dateRange": { "from": "2024-01-01", "to": "2024-01-31" },
    "filters": [
      { "field": "campaign_id", "operator": "in", "value": ["12345", "12346"] }
    ],
    "limit": 1000,
    "ownerId": 67890
  }' \
  'https://adfox.yandex.ru/api/v2/reports'

Пример ответа (HTTP 202)

{
  "result": {
    "taskId": "umr-a-rsr-b5555555-5555-5555-5555-555555555501",
    "status": "PENDING"
  }
}

Сохраните taskId — он понадобится для проверки статуса и получения результата.

Ошибки

С кодами ошибок можно ознакомиться на странице Коды ошибок.

Была ли статья полезна?

Получить доступный диапазон дат

Проверить готовность отчета