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

Endpoint
Авторизация: заголовок `Authorization: Bearer <ваш_токен>`
URL, по которому отправляются запросы к API


POST https://api.targetads.io/v1/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). Если у обоих фильтров даты пустые, запрос отклоняется с 400 и сообщением `Interaction or Target DateTo and DateFrom is required`.
InteractionFilter
__________________________________________________________________________________
* Обратите внимание: `InteractionType` — это строка (string), а не массив. Только одно значение на запрос
TargetFilter
__________________________________________________________________________________
Размер тела запроса
__________________________________________________________________________________
Максимум - 1 МБ.
Доступные поля
Поля взаимодействий
___________________________________________________________________________
UTM-метки
___________________________________________________________________________
Аналитические ID
___________________________________________________________________________
Медиа-информация
___________________________________________________________________________
Поля целевых событий
___________________________________________________________________________
E-commerce поля
___________________________________________________________________________
Веса атрибуции
___________________________________________________________________________
Примеры запросов
Базовый анализ пути к покупке
curl -X POST "https://api.targetads.io/v1/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": "2026-06-01",
      "DateTo": "2026-06-30"
    },
    "TargetFilter": {
      "DateFrom": "2026-06-01",
      "DateTo": "2026-06-30",
      "EventType": ["Purchase"]
    },
    "Limit": 10000
  }'
Анализ пути с UTM метками
curl -X POST "https://api.targetads.io/v1/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": {
      "DateFrom": "2026-06-01",
      "DateTo": "2026-06-30",
      "UtmSource": ["google", "facebook"]
    },
    "TargetFilter": {
      "DateFrom": "2026-06-01",
      "DateTo": "2026-06-30",
      "EventType": ["Purchase"]
    }
  }'
Фильтр по конкретным креативам и размещениям
curl -X POST "https://api.targetads.io/v1/reports/path_to_conversion?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "InteractionTime",
      "InteractionType",
      "InteractionMediaCampaignName",
      "InteractionMediaPlacementName",
      "TargetEventName",
      "MLI30"
    ],
    "InteractionFilter": {
      "DateFrom": "2026-06-01",
      "DateTo": "2026-06-30",
      "PlacementId": [12345, 12346],
      "CreativeId": [98765]
    },
    "TargetFilter": {
      "DateFrom": "2026-06-01",
      "DateTo": "2026-06-30",
      "EventType": ["Purchase"]
    }
  }'
Формат ответа
Успешный ответ (200 OK)
Ответ — JSON-структура с массивом колонок, массивом строк и счётчиком.
Все значения в `Rows` сериализованы как строки.
{
  "Columns": [
    "InteractionTime",
    "InteractionType",
    "InteractionMediaCampaignName",
    "TargetEventName",
    "TargetEcomAmount",
    "MLI30"
  ],
  "Rows": [
    [
      "2026-06-15 14:23:45",
      "Impression",
      "Summer Campaign 2026",
      "Purchase",
      "12990.00",
      "1.0"
    ]
  ],
  "CountRows": 1
}
Использования пагинации для больших периодов
При выгрузке данных за большие периоды количество строк в отчете может превышать технический лимит API. В этом случае данные необходимо получать постранично, используя параметры Limit и Offset.

Limit задает максимальное количество строк, которое нужно вернуть в одном запросе. Offset задает смещение — количество строк, которые нужно пропустить перед началом выдачи следующей порции данных.

Рекомендуемый подход:
1. Выполнить первый запрос с Offset = 0 и выбранным значением Limit.
2. Сохранить полученные строки.
3. Если количество строк в ответе равно Limit, выполнить следующий запрос, увеличив Offset на значение Limit.
4. Повторять запросы до тех пор, пока API не вернет меньше строк, чем указано в Limit. Это означает, что получена последняя страница данных.
def get_all_paths(project_id, date_from, date_to):
    offset = 0
    limit = 100000
    all_paths = []

    while True:
        response = get_path_to_conversion(
            project_id=project_id,
            date_from=date_from,
            date_to=date_to,
            offset=offset,
            limit=limit
        )

        all_paths.extend(response['data'])

        if len(response['data']) < limit:
            break

        offset += limit

    return all_paths
Такой способ позволяет корректно выгружать большие объемы данных без потери строк: каждая следующая итерация запроса получает следующую страницу результата. При построении интеграции также необходимо учитывать общий rate limit API и таймаут выполнения запроса. Для очень больших периодов рекомендуется дополнительно дробить выгрузку по датам.
Ответ в случае ошибки валидации (400 Bad Request)
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "ErrorsField": [
    {
      "FiledName": "Interaction or Target DateTo and DateFrom is required",
      "Value": ""
    }
  ]
}
Ключ `FiledName` пишется именно так (исторически закреплённое имя поля
в JSON-контракте, не опечатка в документации).
Коды ошибок

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


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

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


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

Таймаут: 600 секунд