Raw data API v.2

Raw Data API v2

Raw Data API v2 предоставляет доступ к детальным данным о взаимодействиях пользователей с рекламой на уровне отдельных событий. API работает асинхронно: в ответ на запрос возвращается job_id, по которому затем проверяется статус и скачивается готовый файл отчёта.

Формат выгрузки — CSV в gzip-сжатии (расширение .csv.gz). Файл хранится

во внешнем объектном хранилище; ссылка для скачивания возвращается в статусе задачи, когда отчёт готов.

Endpoints

Базовый URL: `https://api.targetads.io`
Авторизация: заголовок `Authorization: Bearer <ваш_токен>`.

Создание задачи

POST https://api.targetads.io/v2/reports/raw_reports?project_id={project_id}

Query-параметры
__________________________________________________________________________________

Тело запроса (JSON)
__________________________________________________________________________________

Важно: один запрос рассчитан на один тип события (InteractionType — строка).

Чтобы получить данные по нескольким типам, отправьте отдельные запросы на каждый тип.

Ограничения периода (окна дат)

- `DateFrom` должен быть не раньше, чем «сегодня минус 90 дней».
- Длина окна (`DateTo − DateFrom`) не должна превышать 3 дня.
- `DateFrom` ≤ `DateTo`.

Если требуется выгрузка за больший период — разбейте её на несколько задач
с непересекающимися окнами по 3 дня.

Размер тела запроса
- Максимум — 1 МБ.

Допустимые значения InteractionType
__________________________________________________________________________________

Доступные поля по типам события __________________________________________________________________________________

Набор доступных полей зависит от выбранного InteractionType. В таблице ниже
указано, для каких типов поле доступно. Если поле запрошено для типа,
в котором оно недоступно, запрос завершится ошибкой.

Сокращения в столбцах:
- I — Impression
- Cl — Click
- S — Session
- E — Event / AddToCart / Purchase
__________________________________________________________________________________

Общие поля

Геолокация и устройство

Медиа и размещение

Для получения человекочитаемых названий уровней трекинга используйте Meta API

Если в сырых данных вам нужны названия кампаний, размещений, источников, креативов и других уровней трекинга, используйте Meta API. В Raw Data API эти сущности передаются в виде ID, а их человекочитаемые названия необходимо получать отдельно через справочный метод.

Такой подход позволяет не перегружать сырые логи лишними данными. Raw Data API может отдавать десятки миллионов строк, и если в каждой строке передавать не только ID, но и полные названия кампаний, размещений, источников и креативов, объём выгрузки существенно вырастет. Это увеличит время передачи данных, нагрузку на сеть и скорость обработки отчёта.

Meta API решает эту задачу эффективнее: вы один раз загружаете справочник вида ID → название, а затем используете его для расшифровки сырых данных. При этом можно запрашивать только те параметры, которые действительно нужны для анализа, не увеличивая объём Raw Data API.

URL и UTM

Идентификаторы пользователя

Целевые события (только Event / AddToCart / Purchase)

E-commerce (только Event / AddToCart / Purchase)

Процесс получения данных

Шаг 1. Создание задачи

bash
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionType",
      "InteractionPlacementId",
      "InteractionDomain"
    ],
    "DateFrom": "2026-06-01",
    "DateTo": "2026-06-01",
    "InteractionType": "Impression",
    "PlacementId": [12345, 12346]
  }'

Ответ - 202 Accepted

json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CREATED",
  "created_at": "2026-06-01T10:00:00Z"
}

Шаг 2. Проверка статуса

bash
curl "https://api.targetads.io/v2/jobs/550e8400-e29b-41d4-a716-446655440000?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN"

Задача в работе:

json
{
  "job_id": "550e8400-...",
  "report_type": "raw_reports",
  "status": "PROCESSING",
  "created_at": "2026-06-01T10:00:00Z"
}

Задача готова:

json
{
  "job_id": "550e8400-...",
  "report_type": "raw_reports",
  "status": "DONE",
  "created_at": "2026-06-01T10:00:00Z",
  "completed_at": "2026-06-01T10:04:12Z",
  "row_count": 150000,
  "file_size_bytes": 8500000,
  "format": "csv.gz",
  "download_url": "...",
  "download_expires_at": "2026-06-02T10:04:12Z",
  "expires_at": "2026-06-02T10:04:12Z"
}

Шаг 3. Скачивание файла
Файл выгрузки — CSV, сжатый gzip. Ссылка для скачивания возвращается в поле
`download_url` и содержит параметр `response-content-encoding=gzip
Чтобы curl распаковал поток автоматически: `.

`bash
curl --compressed -o report.csv "${download_url}"

Или скачать в сжатом виде и распаковать вручную:

bash
curl -o report.csv.gz "${download_url}"
gunzip report.csv.gz

Шаг 4. (Опционально) Список задач проекта

bash
curl "https://api.targetads.io/v2/jobs?project_id=<Ваш project ID>&limit=20&offset=0" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

json
{
  "jobs": [
    {
      "job_id": "550e8400-...",
      "report_type": "raw_reports",
      "status": "DONE",
      "created_at": "2026-06-01T10:00:00Z",
      "completed_at": "2026-06-01T10:04:12Z",
      "row_count": 150000,
      "file_size_bytes": 8500000,
      "format": "csv.gz"
    }
  ],
  "total": 1
}

Шаг 5. (Опционально) Отмена задачи
Отменить можно задачу, которая ещё не завершилась (статусы CREATED, PROCESSING). DONE / FAILED / CANCELLED отменить нельзя — API вернёт 400.

bash
curl -X DELETE "https://api.targetads.io/v2/jobs/550e8400-...?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN"

Ответ:

json
{
  "job_id": "550e8400-...",
  "status": "CANCELLED",
  "prev_status": "PROCESSING"
}

Статусы задач

Формат ошибки

В случае некорректного запроса API возвращает 4xx с телом:

json
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "ErrorsField": [
    {
      "FiledName": "DateTo",
      "Value": "2026-06-01",
      "Message": "Date window too wide: 9 days. Maximum is 3 days. Split your request into multiple jobs with non-overlapping ≤3-day windows."
    }
  ]
}

Поле `Message` присутствует не всегда — оно появляется, когда сервер может
дать конкретную подсказку (например, как разбить запрос). Если подсказки нет —
поле просто отсутствует.

Коды ошибок

Сводка лимитов и ограничений

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

Базовая выгрузка показов

bash
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionType",
      "InteractionPlacementId",
      "InteractionCreativeId",
      "InteractionDomain"
    ],
    "DateFrom": "2026-06-01",
    "DateTo": "2026-06-01",
    "InteractionType": "Impression"
  }'

Сессии с гео и UTM

bash
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionUserID",
      "InteractionCountry",
      "InteractionCity",
      "InteractionUrlPath",
      "InteractionUtmSource",
      "InteractionUtmCampaign"
    ],
    "DateFrom": "2026-06-01",
    "DateTo": "2026-06-01",
    "InteractionType": "Session"
  }'

E-commerce покупки

bash
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionUserID",
      "InteractionEcomId",
      "InteractionEcomAmount",
      "InteractionEcomItemsName",
      "InteractionEcomItemsPrice"
    ],
    "DateFrom": "2026-06-01",
    "DateTo": "2026-06-01",
    "InteractionType": "Purchase"
  }'