TargetADS HELP CENTER
Path to Conversion API

Path to Conversion API предоставляет данные о пути пользователя к конверсии: все касания и целевые события вместе с весами атрибуционных моделей. Помогает анализировать customer journey и определять, какие точки контакта повлияли на конверсию.

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


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

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

Endpoints

Базовый URL: `https://api.targetads.io`
Авторизация: заголовок `Authorization: Bearer <ваш_токен>`.
Создание задачи
POST https://api.targetads.io/v2/reports/path_to_conversion?project_id={project_id}
Query-параметры
__________________________________________________________________________________
Тело запроса (JSON)
__________________________________________________________________________________

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

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


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

- Максимум — 1 МБ.
Доступные поля
________________________________________________________________________________
Всего 119 полей. Набор одинаков для обоих типов касания.
Каждая строка отчёта — это пара «касание × целевое событие». Сторона видна по имени поля: Interaction* описывает касание, Target* — целевое событие.
Общие поля
Геолокация и устройство
Медиа и размещение
Для получения человекочитаемых названий уровней трекинга используйте Meta API
Для получения человекочитаемых названий уровней трекинга используйте Meta API
Если в данных о пути к конверсии вам нужны названия кампаний, размещений, источников, креативов и других уровней трекинга, используйте Meta API. В Path to Conversion API v2 эти сущности передаются в виде ID, а их человекочитаемые названия необходимо получать отдельно через справочный метод.
URL и UTM
Важно: у показов (Impression) поля UTM и InteractionUrlPath всегда пустые — у показа нет страницы перехода.
Идентификаторы пользователя
Целевые события
E-commerce
Веса атрибуции
Имя веса собирается из модели и окна атрибуции в днях: <модель><окно>. Например, FLI30 — модель «последнее касание» по всем касаниям с окном 30 дней.
Процесс получения данных
Шаг 1. Создание задачи
curl -X POST "https://api.targetads.io/v2/reports/path_to_conversion?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "CSV",
    "Fields": [
      "TargetEventDate",
      "TargetEventName",
      "InteractionType",
      "InteractionTime",
      "InteractionPlacementId",
      "FLI30"
    ],
    "TargetFilter": {
      "DateFrom": "2026-08-30",
      "DateTo": "2026-08-31"
    },
    "InteractionFilter": {
      "InteractionType": "Impression"
    }
  }'
Ответ - 202 Accepted
json
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CREATED",
  "created_at": "2026-09-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": "path_to_conversion",
  "status": "PROCESSING",
  "created_at": "2026-08-28T10:00:00Z"
}
Задача готова:
json
{
  "job_id": "550e8400-...",
  "report_type": "path_to_conversion",
  "status": "DONE",
  "created_at": "2026-08-28T10:00:00Z",
  "completed_at": "2026-08-28T10:04:12Z",
  "row_count": 150000,
  "file_size_bytes": 8500000,
  "format": "csv.gz",
  "download_url": "...",
  "download_expires_at": "2026-08-29T10:04:12Z",
  "expires_at": "2026-08-29T10: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": "path_to_conversion",
      "status": "DONE",
      "created_at": "2026-08-28T10:00:00Z",
      "completed_at": "2026-08-28T10: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
{
  "ErrorMessage": "validate error",
  "ErrorCode": 400,
  "ErrorsField": [
    {
      "FiledName": "Fields",
      "Value": "TargetEventNmae",
      "Message": "Unknown field 'TargetEventNmae' in Fields for V2 path_to_conversion. Check the field name. See https://targetads.io/help/path_to_conversion_api_v2."
    }
  ]
}
Поле `Message` присутствует не всегда — оно появляется, когда сервер может
дать конкретную подсказку (например, как разбить запрос). Если подсказки нет —
поле просто отсутствует.
Коды ошибок
Сводка лимитов и ограничений
Примеры запросов
Все касания на пути к конверсиям за период
bash
curl -X POST "https://api.targetads.io/v2/reports/path_to_conversion?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "CSV",
    "Fields": [
      "TargetEventDate",
      "TargetEventName",
      "TargetEcomAmount",
      "InteractionType",
      "InteractionTime",
      "InteractionPlacementId",
      "InteractionCreativeId",
      "MLI30"
    ],
    "TargetFilter": {
      "DateFrom": "2026-08-30",
      "DateTo": "2026-08-31"
    }
  }'
Только медийные касания
bash
curl -X POST "https://api.targetads.io/v2/reports/path_to_conversion?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "CSV",
    "Fields": [
      "TargetEventDate",
      "TargetEventName",
      "InteractionTime",
      "InteractionPlacementId",
      "InteractionSSP",
      "FFI30",
      "FLI30",
      "FL30"
    ],
    "TargetFilter": {
      "DateFrom": "2026-08-30",
      "DateTo": "2026-08-31"
    },
    "InteractionFilter": {
      "InteractionType": "Impression"
    }
  }'
Переходы с UTM-метками
bash
curl -X POST "https://api.targetads.io/v2/reports/path_to_conversion?project_id=<Ваш project ID>" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "CSV",
    "Fields": [
      "TargetEventDate",
      "TargetEventName",
      "InteractionTime",
      "InteractionDomain",
      "InteractionUrlPath",
      "InteractionUtmSource",
      "InteractionUtmMedium",
      "InteractionUtmCampaign",
      "FLI30"
    ],
    "TargetFilter": {
      "DateFrom": "2026-08-30",
      "DateTo": "2026-08-31"
    },
    "InteractionFilter": {
      "InteractionType": "PageView"
    }
  }'