TargetADS HELP CENTER
Path to Conversion API v2
Path to Conversion API предоставляет детальную информацию о пути пользователя к конверсии, включая все медийные касания и целевые события. API помогает анализировать customer journey и понимать, какие точки контакта влияют на конверсию.
Ключевые изменения по сравнению с 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/path_to_conversion?project_id={project_id}
Параметры запроса
Query-параметры
___________________________________________________________________________
Тело запроса
{
  "ResponseType": "JSON",
  "Fields": [
    "InteractionTime",
    "InteractionType",
    "InteractionMediaCampaignName",
    "TargetEventName"
  ],
  "InteractionFilter": {
    "DateFrom": "2024-01-01",
    "DateTo": "2024-01-31"
  },
  "TargetFilter": {
    "DateFrom": "2024-01-01",
    "DateTo": "2024-01-31",
    "EventType": ["Purchase"]
  },
  "Offset": 0,
  "Limit": 10000
}
Параметры тела запроса
__________________________________________________________________________________
  • Обязательно указать хотя бы один из фильтров: `InteractionFilter` или `TargetFilter` (с заполненными DateFrom и DateTo)
InteractionFilter
__________________________________________________________________________________
* Обратите внимание: `InteractionType` — это строка (string), а не массив. Допустимые значения: `PageView`, `Impression`.
TargetFilter
__________________________________________________________________________________
Доступные поля
Поля взаимодействий
___________________________________________________________________________
UTM-метки
___________________________________________________________________________
Аналитические ID
___________________________________________________________________________
Медиа-информация
___________________________________________________________________________
Поля целевых событий
___________________________________________________________________________
E-commerce поля
___________________________________________________________________________
Веса атрибуции
___________________________________________________________________________
Процесс получения данных
Шаг 1: создание задачи
curl -X POST "https://api.targetads.io/v2/reports/path_to_conversion?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionType",
      "InteractionMediaCampaignName",
      "TargetEventName",
      "TargetEcomAmount",
      "MLI30"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31"
    },
    "TargetFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "EventType": ["Purchase"]
    },
    "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": "DONE",
  "row_count": 5000,
  "file_size_bytes": 250000,
  "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/path_to_conversion?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionType",
      "InteractionMediaCampaignName",
      "TargetEventName",
      "TargetEcomAmount",
      "MLI30"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31"
    },
    "TargetFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "EventType": ["Purchase"]
    },
    "Limit": 10000
  }'
Анализ пути с UTM метками
curl -X POST "https://api.targetads.io/v2/reports/path_to_conversion?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionType",
      "InteractionMediaCampaignName",
      "InteractionUtmSource",
      "InteractionUtmMedium",
      "TargetEventName",
      "FL30",
      "MLI30"
    ],
    "InteractionFilter": {
      "UtmSource": ["google", "facebook"]
    },
    "TargetFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "EventType": ["Purchase"]
    }
  }'
Статусы задачи
Ответ в случае ошибки
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "Errors": [
    {
      "Error": true,
      "FailedField": "Interaction or Target DateTo and DateFrom is required",
      "Value": ""
    }
  ]
}
Коды ошибок

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


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

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


Максимум записей: 100 000
Минимум полей: 3
Максимум значений в фильтре:
- MediaCampaignId/MediaPlacementId: 20
Rate limit: 40 запросов в минуту на project_id
InteractionType: только `PageView` или `Impression` (string, не array)
Обязательно указать хотя бы один фильтр с датами

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

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