TargetADS HELP CENTER
Raw Data API v2
Raw Data API предоставляет доступ к детальным данным о взаимодействиях пользователей с рекламными материалами на уровне отдельных событий. API позволяет получать необработанные данные для глубокой аналитики и построения собственных отчетов.
Ключевые изменения по сравнению с v1:

API v2 использует те же параметры запроса что и v1 — те же поля, фильтры, лимиты. Для перехода достаточно заменить /v1/ на /v2/ в URL и адаптировать получение результата.

Главное отличие — v2 работает асинхронно. В v1 запрос блокировался до готовности данных и возвращал JSON в теле ответа. В v2 запрос мгновенно возвращает job_id, клиент периодически проверяет статус через GET /v2/jobs/{job_id}, и когда данные готовы — скачивает CSV по ссылке. Это убирает таймауты при больших выгрузках.

При отправке одинаковых запросов повторно, система вернёт первый `job_id` без создания дубликата. Если отчёт уже был готов - статус отобразится сразу как `DONE`.
Endpoint
URL, по которому отправляются запросы к API
POST /v2/reports/raw_reports?project_id={project_id}
Параметры запроса
Query-параметры
__________________________________________________________________________________
Тело запроса
{
  "ResponseType": "JSON",
  "Fields": [
    "InteractionTime",
    "InteractionDeviceID",
    "InteractionType",
    "InteractionMediaCampaignName",
    "InteractionDomain"
  ],
  "InteractionFilter": {
    "DateFrom": "2024-01-01",
    "DateTo": "2024-01-31",
    "InteractionType": ["Impression", "Click"],
    "MediaCampaignId": [12345, 12346]
  },
  "Stable": 1,
  "Offset": 0,
  "Limit": 10000
}
Параметры тела запроса
__________________________________________________________________________________
InteractionFilter
__________________________________________________________________________________
Допустимые значения InteractionType
__________________________________________________________________________________
Допустимые значения DeviceType
__________________________________________________________________________________
Как работать с фильтром 'Stable':

Параметр Stable передаётся в корне JSON-запроса. Управляет фильтрацией по стабильности InteractionDeviceID:

Не передан — возвращаются все записи без фильтрации
"Stable": 1 — только стабильные DeviceID (кука не новая)
"Stable": 0 — только нестабильные DeviceID (кука новая)

Допустимые значения: 0 или 1. Любое другое значение (например 2) будет отклонено валидацией.
Пример запроса со стабильными DeviceID:
{
"ProjectId": 11111,
"ResponseType": "JSON",
"Fields": ["InteractionDeviceID", "InteractionTime", "InteractionType"],
"Stable": 1,
"InteractionFilter": {
"DateFrom": "2025-01-01",
"DateTo": "2025-01-31",
"InteractionType": ["Impression"]
}
}
Доступные поля
Поля взаимодействий
___________________________________________________________________________
Устройство и браузер
___________________________________________________________________________
Геолокация
___________________________________________________________________________
Медиа-информация
__________________________________________________________________________________
URL и навигация
__________________________________________________________________________________
UTM метки
__________________________________________________________________________________
Аналитические ID
___________________________________________________________________________
Целевые события
___________________________________________________________________________
E-commerce данные
___________________________________________________________________________
Кастомные параметры
___________________________________________________________________________
Процесс получения данных
Шаг 1: создание задачи
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionType",
      "InteractionMediaCampaignName",
      "InteractionDomain"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "InteractionType": ["Impression", "Click"]
    },
    "Limit": 10000
  }'
Ответ `202 Accepted`:
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CREATED",
  "created_at": "2024-01-15T10:00:00Z",
  "estimated_seconds": 120
}
Шаг 2: Проверка статуса
curl "https://api.targetads.io/v2/jobs/{job_id}?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN"
Процесс просчёта
{
  "job_id": "550e8400-...",
  "status": "PROCESSING"
}
По готовности:
{
  "job_id": "550e8400-...",
  "status": "DONE",
  "row_count": 150000,
  "file_size_bytes": 8500000,
  "download_url": "https://storage.yandexcloud.net/...",
  "download_expires_at": "2024-01-15T11:00:00Z"
}
Шаг 3: скачивание csv
curl -o report.csv "https://storage.yandexcloud.net/..."
Примеры запросов
Базовая выгрузка показов и кликов
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionType",
      "InteractionMediaCampaignName",
      "InteractionDomain"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "InteractionType": ["Impression", "Click"]
    },
    "Limit": 10000
  }'
Детальный анализ с геолокацией
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionType",
      "InteractionMediaCampaignName",
      "InteractionCountry",
      "InteractionCity",
      "InteractionDeviceType",
      "InteractionBrowserName"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "InteractionType": ["Impression"],
      "MediaCampaignId": [12345, 12346],
      "DeviceType": ["mobile", "desktop"]
    },
    "Limit": 50000
  }'
E-commerce события (покупки)
curl -X POST "https://api.targetads.io/v2/reports/raw_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionDeviceID",
      "InteractionEcomId",
      "InteractionEcomAmount",
      "InteractionEcomItemsName",
      "InteractionEcomItemsPrice"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "InteractionType": ["Purchase"]
    }
  }'
```
Статусы задачи
Ответ в случае ошибки
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "Errors": [
    {
      "Error": true,
      "FailedField": "Interaction or Target DateTo and DateFrom is required",
      "Value": ""
    }
  ]
}
Коды ошибок

Лимиты и ограничения


API имеет технические ограничения, которые следует

учитывать при построении интеграции:


Максимум записей за запрос: 10,000,000
Минимум полей: 3
Максимум кампаний в фильтре: 20
Максимум плейсментов в фильтре: 20
Максимум значений в остальных фильтрах: 5
Rate limit: 40 запросов в минуту

Время жизни ссылки на скачивание: 1 час

Время хранения отчета: 24 часа