Generate a report

Send a POST request specifying the required metrics, dimensions, filters, and date range. This will create an asynchronous report‑generation task or return an existing taskId if the same request was made before.

The response returns a taskId that you can use to track the report status.

POST /api/v2/reports

Characteristic	Value
Method	`POST`
Path	`/api/v2/reports`
Headers	`Content-Type: application/json` (required)
Success	`202 Accepted`

Request body

Field	Type	Required status	Description
`metrics`	Array of strings	Logically required	A non‑empty array, where each element is a non‑empty string. `name` values from `GET /metadata → metrics`.
`dimensions`	Array of strings	Not required	Dimensions. `name` values from `GET /metadata → dimensions`. An empty array or missing field is treated as “no dimensions“.
`filters`	Array of objects	Not required	Filters. See the structure below.
`dateRange`	object	Logically required	Report period. Fields `from` and `to` in `YYYY-MM-DD` format.
`limit`	Integer	Not required	The maximum rows returned. If provided, the value must fall within the range of 1 to 1,000,000 inclusive.
`ownerId`	Integer > 0	Required for advertisers	ID of the admin account.

Structure `filters[]`

Field	Type	Description
`field`	String	Filter field. `field` value from `GET /metadata → filters`.
`operator`	String	Comparison operator (see the table “Allowed `operator` values in filters” below).
`value`	JSON	Required, must not be `null`. For scalar operators, the value must be a scalar (string/number/boolean). For `in`, `notIn`, and `hasAny`, it must be a non‑empty array of scalars of the same type.

Error‑message indexes are zero‑based: filters[0].field, …

Allowed `operator`values in filters

Operator	Description
`eq`	Equal to.
`ne`	Not equal to.
`lt` / `le`	Less than / less than or equal to.
`gt` / `ge`	Greater than / greater than or equal to.
`like` / `notLike`	Matches / does not match the pattern.
`in`	Included in the list of values.
`notIn`	Not included in the list of values.
`hasAny`	Intersects with the set.

Object `dateRange`

Field	Type	Description
`from`	string	Required, not empty. Date in calendar format: `YYYY-MM-DD`.
`to`	string	Must satisfy `from ≤ to`.

The number of calendar days in the date range (inclusive) must not exceed maxDateRangeDays from the metadata (365).

Sample request

curl -X POST \
  -H 'Authorization: OAuth <token>' \
  -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'

Sample response (HTTP 202)

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

Save taskId. You'll need it to check the report status and retrieve the results.

Errors

For error codes, see the Error codes page.

Was the article helpful?

Get the allowed date range

Check the report status