Fraud Reports API v2
Fraud Reports API v2 предоставляет детальные данные о показах и кликах с признаками GIVT (General Invalid Traffic) и причинами невалидности. API работает асинхронно: в ответ возвращается job_id, по которому проверяется статус и скачивается готовый отчёт.

Формат выгрузки — CSV в gzip-сжатии (.csv.gz). Данные за период возвращаются одним файлом.
Эндпоинты
Базовый URL: https://api.targetads.io
Authorization: Bearer YOUR_TOKEN
Создание задачи
Query-параметры

project_id — обязательный параметр, ID проекта.

Авторизация: Authorization: Bearer YOUR_TOKEN. Токен должен иметь доступ к проекту и категории fraud-отчётов. В выгрузку входят только доступные токену размещения. Если ни одно из запрошенных размещений недоступно, API вернёт 403.

Создание и отмена задач входят в общий лимит 40 запросов в минуту на project_id.
Тело запроса (JSON)
{
  "Fields": [
    "EventDateTime",
    "SysName",
    "DeviceId",
    "Domain",
    "Givt",
    "GivtReasonDataCentre",
    "GivtReasonCrawler"
  ],
  "InteractionFilter": {
    "DateFrom": "2026-10-01",
    "DateTo": "2026-10-31",
    "SysName": [
      "Impression"
    ]
  }
}
Параметры тела запроса

Максимальный размер тела запроса — 1 МБ.
InteractionFilter

Даты задают московские сутки. DateFrom и DateTo включаются в период. Например, 2026-10-01 — 2026-10-31 означает интервал с 00:00 1 октября до 00:00 1 ноября, не включая верхнюю границу.

Период одного запроса — до 31 дня. DateFrom — не раньше 93 дней назад. DateTo — не позже вчерашнего дня по московскому времени. Для большего периода создайте несколько задач с непересекающимися окнами.
Доступные поля для выгрузки
В Fields можно передать от 1 до 24 названий без повторов. Неизвестное название — ошибка 400. Названия чувствительны к регистру.
Порядок колонок может отличаться от порядка Fields. Читайте названия из первой строки CSV и сопоставляйте значения по заголовку. Порядок строк не гарантирован: при необходимости отсортируйте выгрузку после скачивания.
PlacementId и CreativeId применяются только в InteractionFilter. В Fields используйте MediaCampaignId и MediaPlacementId. У одного события может быть несколько причин GIVT.
Процесс получения данных
Шаг 1. Создание задачи
Задайте переменные окружения TARGETIO_PROJECT_ID (ID проекта) и TARGETIO_API_TOKEN (токен). Даты в примере замените на нужный период внутри последних 93 дней.
curl -X POST "https://api.targetads.io/v2/reports/fraud_reports?project_id=${TARGETIO_PROJECT_ID}" \
  -H "Authorization: Bearer ${TARGETIO_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "Fields": [
    "EventDateTime",
    "SysName",
    "DeviceId",
    "Domain",
    "Givt",
    "GivtReasonDataCentre",
    "GivtReasonCrawler"
  ],
  "InteractionFilter": {
    "DateFrom": "2026-10-01",
    "DateTo": "2026-10-31",
    "SysName": [
      "Impression"
    ]
  }
}'
Ответ — 202 Accepted
Одинаковый запрос возвращает существующую задачу в CREATED, PROCESSING или DONE до истечения срока файла. После FAILED, CANCELLED или истечения срока создаётся новая задача.
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CREATED",
  "created_at": "2026-11-02T10:00:00Z"
}
Шаг 2. Проверка статуса
Подставьте job_id из ответа POST. Проверяйте статус, например, раз в 5 секунд до DONE, FAILED, CANCELLED или EXPIRED. GET /v2/jobs и GET /v2/jobs/{job_id} исключены из лимита 40 запросов в минуту.
curl "https://api.targetads.io/v2/jobs/550e8400-e29b-41d4-a716-446655440000?project_id=${TARGETIO_PROJECT_ID}" \
  -H "Authorization: Bearer ${TARGETIO_API_TOKEN}"
Задача готова: DONE
Файл доступен 48 часов после завершения задачи. Точное время истечения срока указано в expires_at и download_expires_at.
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "report_type": "fraud_reports",
  "status": "DONE",
  "created_at": "2026-11-02T10:00:00Z",
  "completed_at": "2026-11-02T10:01:40Z",
  "row_count": 1250000,
  "file_size_bytes": 31000000,
  "format": "csv.gz",
  "download_url": "https://example.com/reports/example.csv.gz",
  "download_expires_at": "2026-11-04T10:01:40Z",
  "expires_at": "2026-11-04T10:01:40Z"
}
Шаг 3. Скачивание файла
Сохраните download_url из ответа API в переменной окружения TARGETIO_DOWNLOAD_URL. Скачайте CSV.gz и распакуйте его. Повторное скачивание не продлевает срок хранения файла.
curl --fail --location --output report.csv.gz "${TARGETIO_DOWNLOAD_URL}" &&
  gzip --decompress --stdout report.csv.gz > report.csv
Формат ошибки
Данные ещё не готовы: FAILED
Причина сбоя возвращается в error_message. Если данные ещё не готовы, повторите POST позже. Отчёт формируется только при наличии данных за весь запрошенный период.
{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "report_type": "fraud_reports",
  "status": "FAILED",
  "error_message": "Данные за 2026-10-31 ещё готовятся, повторите запрос позже."
}
Ошибка валидации: HTTP 400
FiledName — имя параметра, Value — значение, Message — пояснение (может отсутствовать). Имя FiledName соответствует формату ответа API.
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "ErrorsField": [
    {
      "FiledName": "DateTo",
      "Value": "2026-08-01..2026-09-15",
      "Message": "V2 fraud_reports accepts up to 31 days per request (got 46 days). Split the period into several jobs."
    }
  ]
}

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

Коды ответов