Fraud Reports API
Fraud Reports API предоставляет детальные данные о событиях с маркерами недействительного трафика (GIVT — General Invalid Traffic). API позволяет получить сырые данные по каждому событию с детализацией причин GIVT.
Endpoint
URL, по которому отправляются запросы к API
POST /v1/reports/fraud_reports?project_id={project_id}
Параметры запроса
Query-параметры
__________________________________________________________________________________

`project_id` (обязательный) - ID проекта
Тело запроса
{
  "ResponseType": "JSON",
  "Fields": [
    "EventDateTime",
    "SysName",
    "DeviceId",
    "Givt",
    "GivtReasonDataCentre"
  ],
  "InteractionFilter": {
    "DateFrom": "2024-01-01",
    "DateTo": "2024-01-31",
    "SysName": ["Impression", "Click"]
  },
  "Offset": 0,
  "Limit": 10000
}
Параметры тела запроса
__________________________________________________________________________________
InteractionFilter
__________________________________________________________________________________
Доступные поля
Все поля, доступные для запроса в массиве `Fields`:
__________________________________________________________________________________
> Все значения возвращаются как строки (`toString()`).
Сортировка:
__________________________________________________________________________________
Результаты можно сортировать по полю `EventDateTime`.
Примеры запросов
Базовая выгрузка GIVT
curl -X POST "https://api.targetads.io/v1/reports/fraud_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "EventDateTime",
      "SysName",
      "DeviceId",
      "Givt"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "SysName": ["Impression"]
    },
    "Offset": 0,
    "Limit": 100000
  }'
Детальный анализ GIVT с причинами
curl -X POST "https://api.targetads.io/v1/reports/fraud_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "EventDateTime",
      "SysName",
      "DeviceId",
      "Domain",
      "Givt",
      "GivtReasonDataCentre",
      "GivtReasonCrawler",
      "GivtReasonUnknownDevice",
      "GivtReasonBehavior",
      "GivtReasonSuspiciousActivity"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "SysName": ["Impression"]
    },
    "Limit": 50000
  }'
Анализ по кампаниям с географией
curl -X POST "https://api.targetads.io/v1/reports/fraud_reports?project_id=12486" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "EventDateTime",
      "DeviceId",
      "MediaCampaignId",
      "MediaPlacementId",
      "Country",
      "City",
      "Domain",
      "Givt",
      "GivtReasonDataCentre",
      "GivtReasonCrawler"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31",
      "MediaCampaignId": [12345, 12346]
    },
    "Limit": 200000
  }'
Полная выгрузка с техническими данными
curl -X POST "https://api.targetads.io/v1/reports/fraud_reports?project_id=11111" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ResponseType": "JSON",
    "Fields": [
      "EventDateTime",
      "SysName",
      "DeviceId",
      "SessionId",
      "MediaCampaignId",
      "Domain",
      "SSP",
      "IP",
      "UserAgent",
      "DeviceType",
      "Platform",
      "Country",
      "City",
      "Givt",
      "GivtReasonDataCentre",
      "GivtReasonUnknownDevice",
      "GivtReasonCrawler",
      "GivtReasonBehavior",
      "GivtReasonSuspiciousActivity"
    ],
    "InteractionFilter": {
      "DateFrom": "2024-01-01",
      "DateTo": "2024-01-31"
    },
    "Limit": 1000000
  }'
Формат ответа
Успешный ответ
{
  "data": [
    {
      "EventDateTime": "2024-01-15 14:23:45",
      "SysName": "Impression",
      "DeviceId": "abc123def456",
      "Givt": "true",
      "GivtReasonDataCentre": "true",
      "GivtReasonCrawler": "false",
      "GivtReasonUnknownDevice": "false",
      "GivtReasonBehavior": "false",
      "GivtReasonSuspiciousActivity": "false"
    },
    {
      "EventDateTime": "2024-01-15 14:24:12",
      "SysName": "Click",
      "DeviceId": "xyz789uvw012",
      "Givt": "false",
      "GivtReasonDataCentre": "false",
      "GivtReasonCrawler": "false",
      "GivtReasonUnknownDevice": "false",
      "GivtReasonBehavior": "false",
      "GivtReasonSuspiciousActivity": "false"
    }
  ],
  "count": 2
}
Ошибка валидации
{
  "ErrorCode": 400,
  "ErrorMessage": "validate error",
  "Errors": [
    {
      "Error": true,
      "FailedField": "DateFrom",
      "Tag": "required",
      "Value": null
    }
  ]
}

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


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

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


Максимум записей: 100 000
Максимальный период выгрузки: 93 дня
Максимум кампаний в фильтре: 20
Максимум плейсментов в фильтре: 20
Rate limit: 40 запросов в минуту на project_id

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

Интеграция с Aggregated Data API
Для получения агрегированных метрик GIVT и SIVT используйте Aggregated Data API (`/v1/reports/agg_report`). В агрегированном отчёте доступны метрики `GIVT`, `SIVT`, `PartOfGIVT`.

! Важно: В Aggregated Data API метрика SIVT не может использоваться совместно с кастомными полями (Country, City, HybridCustom, HybridId), т.к. эти поля переключают запрос на таблицу `events`, где SIVT недоступен.
Коды ошибок