Data API

Data API (раніше описаний тут як Server API) дозволяє вашому бекенду читати дані ідентифікації, які TRACIO вже зібрав для вашого workspace: історію відвідувача, окремі сесії та лічильники активності за коротке вікно. Кілька маршрутів також записують — записи акаунтів, користувацькі поля та елементи списків, — щоб ваш бекенд міг доповнювати те, що відомо TRACIO.

Він доповнює Webhooks, а не замінює їх:

Обидві поверхні доступні з тарифу Pro і вище.

Базова URL-адреса

https://api.tracio.ai/v2

Це окремий хост — не той, що у браузерної кінцевої точки (edge.tracio.ai), і не той, що у дашборда (app.tracio.ai). Усі три різні: браузер спілкується з edge вашим публічним ключем, ваш бекенд спілкується з Data API вашим секретним ключем.

Перехід з v1

Маршрути /v1 видалено. Використовуйте /v2: маршрути ті самі, а кожен ключ JSON і кожен параметр запиту записано в snake_case (visitor_id, risk_score, min_risk_score). Ключі всередині ваших власних словників fields і labels — це ваші дані, і вони зберігають початкове написання. JavaScript SDK зберігає свій інтерфейс у camelCase.

Автентифікація

Кожен запит несе ваш секретний ключ як bearer-токен:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Data API працює лише в режимі server-to-server. Заголовки CORS навмисно не повертаються, тож браузер не може його викликати — саме це утримує ваш секретний ключ поза клієнтським кодом. Ніколи не віддавайте секретний ключ у браузер.

Як отримати секретний ключ

Створіть його в дашборді, у розділі API Keys, обравши тип secret.

• Повний ключ показується рівно один раз, під час створення. На нашому боці зберігається лише хеш, тож втрачений ключ відновити неможливо — замість цього ротуйте його.
• Секретний ключ виглядає як tracio_sk_ плюс 43 символи, разом 53. Дашборд показує його за першими кількома символами, щоб ви могли відрізняти ключі один від одного.
• Секретні ключі потребують тарифу Pro або вище; публічний ключ, який використовує браузерний агент, — це окреме несекретне значення з 40 символів.
• Ключ прив'язаний до середовища: production-ключ не бачить відвідувача зі staging — відповіддю буде 404, так само як для даних, яких не існує.

Ротація секретного ключа

Ротація випускає новий ключ і залишає старий робочим ще 7 днів, тож ви можете викотити заміну без простою. Задеплойте новий ключ, переконайтеся, що трафік перейшов на нього, і дайте старому спливти. Публічні ключі не ротуються — вони не є секретами й за задумом видимі у вихідному коді вашої сторінки.

Кінцеві точки

Той самий ключ і той самий хост обслуговують і API рішень, повністю в snake_case:

Їхні результати надходять до вас і як події вебхуків: transaction_state_changed, login_risk, trusted_device_enrolled, trusted_device_revoked і affiliate_threshold_crossed.

Завершальна скісна риска приймається й ігнорується. Невідомий шлях або хибний метод повертають той самий JSON-конверт помилки, що й усе інше, — ніколи не HTML- і не текстову сторінку.

Часове вікно

Будь-яке читання обмежене часовим вікном, яким керують два необов’язкові параметри запиту:

• Гола дата в to включає весь цей день цілком.
• Усе інше відхиляється з 400 invalid_request і повідомленням time must be YYYY-MM-DD or RFC3339.
• Якщо ви не передали ані того, ані іншого, вікном стає повний строк зберігання вашого тарифу, що завершується зараз.
• Вікно, яке сягає в минуле далі, ніж дозволяє ваш тариф, мовчки підрізається, а не відхиляється. Фактично застосоване вікно завжди повертається в meta, тож перевіряйте meta.from і meta.to, а не вважайте, що ваш запит виконано дослівно.

Пошук відвідувача

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

Відповідь несе агреговану історію і містить у собі останню сесію, тож у типовому випадку вистачає одного запиту, а не двох:

{
  "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "first_seen_at": "2026-05-02T10:11:12Z",
  "last_seen_at": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognito_visits": 3,
  "unique_ips": 5,
  "unique_countries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "max_risk_score": 63,
    "avg_bot_score": 12.5,
    "bot_sessions": 7,
    "last_decision": "real"
  },
  "network": {
    "vpn_seen": false,
    "proxy_seen": false,
    "tor_seen": false,
    "datacenter_seen": true,
    "proxy_detected_seen": true,
    "last_isp": "Deutsche Telekom",
    "last_real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" }
  },
  "last_session": {
    "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "account_id": "user_8842",
    "account": { "id": "user_8842", "email": "ann@example.com", "display_name": "Ann Lee" },
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "fields": { "order_ref": "A-1029" },
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "browser": { "name": "Chrome", "version": "126.0" },
    "os": { "name": "macOS", "version": "14.5" },
    "device": "desktop",
    "gpu": "Apple M2",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "connection_type": "residential",
      "proxy_detected": true,
      "real_ip": { "address": "203.0.113.7", "country": "NL", "isp": "KPN" },
      "asn": 3320
    },
    "screen": { "width": 2560, "height": 1600, "color_depth": 30, "pixel_ratio": 2 },
    "locale": { "languages": ["en-US", "de"], "timezone": "Europe/Berlin" },
    "client_hints": { "architecture": "arm", "bitness": "64", "platform_version": "14.5.0" },
    "extensions": [
      {
        "slug": "ublock-origin",
        "name": "uBlock Origin",
        "category": "adblock",
        "risky": false,
        "store_url": "https://chromewebstore.google.com/detail/cjpalhdlnbpafiamejdnhcphjbkeiagm"
      }
    ],
    "bot": { "result": "human", "score": 4.5, "antidetect_score": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "match_type": "exact",
      "match_confidence": 0.99
    },
    "device_info": {
      "device_id": "d_4f9c2e",
      "cross_browser": true,
      "confidence": 0.88,
      "linked_browsers": 2
    },
    "decision": { "action": "real", "risk_score": 12, "suspect_score": 3 }
  },
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Відвідувач, щодо якого немає даних усередині вікна зберігання, віддає 404 not_found з повідомленням visitor not found in the retention window — це не помилка вашої інтеграції, а ознака того, що відвідувач новий або вже вийшов за строк зберігання.

Поля вердикту

Сесія несе два вердикти, і вони відповідають на різні питання — чи був клієнт автоматизованим і до якого загального висновку дійшов рушій ризику:

bot.score і decision.risk_score обидва йдуть у шкалі 0..100. На Business і вище guidance перетворює їх на рекомендації для кожного сценарію на драбині allow → challenge → review → deny — що означає кожен щабель, див. у розділі Guidance. Значення та шкали збігаються з тілом вебхука v3 для того самого візиту, а guidance обчислюється за тими самими правилами.

Список сесій відвідувача

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions?limit=100&min_risk_score=50"

Сесії повертаються починаючи з найсвіжіших:

{
  "items": [
    {
      "request_id": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitor_id": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "next_cursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "has_more": true,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

Пагінація

Посторінкова вибірка побудована на курсорах. Параметрів page або offset немає: передайте отриманий next_cursor назад як cursor і продовжуйте, доки has_more дорівнює true. Остання сторінка може взагалі не містити next_cursor, тож не робіть це поле обов'язковим.

async function allSessions(visitorId: string, secretKey: string) {
  const sessions = []
  let cursor: string | undefined

  do {
    const url = new URL(`https://api.tracio.ai/v2/visitors/${visitorId}/sessions`)
    url.searchParams.set("limit", "500")
    if (cursor) url.searchParams.set("cursor", cursor)

    const res = await fetch(url, { headers: { Authorization: `Bearer ${secretKey}` } })
    if (!res.ok) throw new Error(`Data API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.has_more ? page.next_cursor : undefined
  } while (cursor)

  return sessions
}

Вважайте курсор непрозорим — його вміст є деталлю реалізації і може змінитися. Відредагований курсор відхиляється з 400 invalid_request і повідомленням malformed cursor.

Факти про пристрій

Окрім браузера та ОС, узятих із User-Agent, сесія несе те, що браузер відвідувача повідомляє про машину, очищене на нашому боці. Кожне поле відсутнє, коли візит таких даних не приніс, тож вважайте будь-яке з них необов'язковим.

Розширення браузера

extensions перелічує розширення браузера, виявлені під час візиту, — Pro і вище. Кожен елемент — об’єкт:

Знахідка повідомляється лише після того, як пройшла наші перевірки довіри, — середовище, яке відповідає «встановлено» на будь-яку пробу, або партія довша за дванадцять імен відбраковуються як ненадійні. Тому порожній або відсутній список означає «нічого, що ми змогли підтвердити», а не «розширень не встановлено». Читайте його як свідчення, а не як інвентарний перелік.

Користувацькі поля

fields містить користувацькі пари ключ–значення, які ваша інтеграція прикріпила до візиту, — номер замовлення, назву тарифу, результат оплати. Ключі та значення завжди є рядками: прикріплене число або логічне значення повертається в текстовому вигляді. Як і решта сесії, поле доступне на будь-якому тарифі з доступом до API (Pro і вище) і відсутнє, якщо візит не має полів.

fields читається наново під час кожного запиту, а не копіюється в момент візиту. Поля, прикріплені після візиту (див. Прикріплення полів після візиту), теж потрапляють сюди, тому для того самого візиту fields може містити більше, ніж доставив вебхук.

Не додавайте до користувацьких полів персональні дані — імена, адреси електронної пошти, номери телефонів: натомість прикріплюйте ідентифікатор, який розпізнають ваші власні системи, а те, хто стоїть за акаунтом, передавайте записом акаунта (нижче).

Запис акаунта

account — це ваш запис про акаунт, що стоїть за візитом, — те, що ви востаннє надіслали для цього account_id через POST /v2/accounts/metadata:

{
  "account": { "id": "user-42", "email": "ann@example.com", "display_name": "Ann Lee" }
}

Запис читається наново під час кожного запиту, тож перейменування видно і на старих візитах: блок описує акаунт таким, яким він є зараз, а не яким був у момент візиту. Він доступний на будь-якому тарифі з доступом до API (Pro і вище). Мітки, які ви надіслали разом із записом, не повертаються.

Блок відсутній, коли візит не має пов'язаного акаунта, коли запису для нього немає (або ви очистили його, надіславши порожні значення), і — рідко — коли запис не вдалося прочитати: сесія все одно повертається повністю, а запит не падає, тож вважайте відсутній блок «невідомо», а не «у цього акаунта немає email». Вебхуки цей блок не несуть.

Отримання однієї сесії

Найсвіжіша:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/sessions/latest"

Повертається голий об’єкт сесії — не масив і не загорнутий у конверт. Відвідувач без сесій у вікні віддає 404 not_found з повідомленням no sessions for this visitor in the retention window.

Або за request_id — ідентифікатором, який трапляється й у payload вебхука:

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/sessions/9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31?visitor_id=X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

visitor_id тут необов’язковий, але якщо ви його знаєте, передача помітно прискорює пошук.

identification.drift_score — згладжена поведінкова оцінка, на якій побудовано вердикт про захоплення акаунта, Business і вище, — повертається лише цим читанням однієї сесії. Поведінковий дрейф вимірюється під час візиту, уже після первинної ідентифікації, тож маршрути списку та останньої сесії його опускають. Візит, поведінку якого так і не було оцінено, не має drift_score. Те саме значення надходить до вас через вебхук account_takeover.

Яку відповідь ви отримаєте для виправленого візиту

Вебхук може доставити візит більше одного разу: спочатку primary, потім late або correction у міру надходження повільніших сигналів і поведінкових свідчень, — і пізніша фаза може перевернути попередній вердикт. Data API відповідає за записом primary. Пізніші фази в нього не вливаються, тож для виправленого візиту останній вебхук — новіша відповідь. Якщо ви дієте через кілька хвилин після візиту, надавайте перевагу фазі, отриманій останньою, а не свіжому читанню тут.

Одне працює у зворотний бік: щойно детектор захоплення акаунта спрацював для візиту, guidance тут це відображає, тоді як тіла вебхука identification того самого візиту цієї осі не несуть — вона надходить окремою доставкою account_takeover.

Velocity

Velocity відповідає на питання «скільки цей відвідувач устиг наробити останнім часом» — саме так виглядають перебір облікових даних, тестування карток і масові реєстрації.

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v2/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y/velocity?window=1h"

window приймає 1h, 24h або 7d, за замовчуванням — 24h. Будь-яке інше значення відхиляється з 400 invalid_request і повідомленням window must be one of: 1h, 24h, 7d.

{
  "window": "1h",
  "events": 37,
  "unique_ips": 9,
  "unique_countries": 3,
  "unique_accounts": 12,
  "bot_events": 4,
  "meta": {
    "plan": "business",
    "retention_days": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

unique_accounts рахує різні значення linkedId, які ви надіслали для цього пристрою, — див. Зв’язування акаунтів. bot_events доступне на Business і вище; на Pro ключ відсутній.

Метадані акаунтів

TRACIO знає ваші акаунти лише за ідентифікатором, який ваш сайт передає як linkedId, — непрозорим рядком на кшталт usr_8412. Надішліть зрозумілі людині мітки один раз, і кожен екран дашборда, де показано цей акаунт, покаже ім'я або email замість сирого ідентифікатора, а об'єкт сесії поверне їх у своєму блоці account. Ніщо тут не впливає на детекцію та оцінку — це шар відображення.

curl -s -X POST "https://api.tracio.ai/v2/accounts/metadata" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"accounts":[
        {"account_id":"usr_8412","email":"ann@example.com","display_name":"Ann Lee","labels":{"tier":"vip"}},
        {"account_id":"usr_9130","display_name":"Bob Ray"}
      ]}'

{ "updated": 2 }

• Персональним даним про акаунт місце тут, а не в fields. Email чи ім'я, надіслані сюди, живуть лише в записі акаунта вашого workspace: вони не зберігаються для кожного візиту, не записуються в сторінку, а одне надсилання оновлює кожен візит цього акаунта.
• Область дії — workspace і середовище ключа. Staging-ключ ніколи не перезапише те, що production-ключ записав для того самого ідентифікатора акаунта.
• Кожне надсилання — повне перезаписування, а не патч. Поля, які ви опустили, зберігаються порожніми — надсилайте запис повністю щоразу. Так само ви й очищаєте значення.
• Невідомі поля відхиляються з 400 invalid_request, і один хибний елемент відхиляє весь пакет — помилка називає його позицію. Повторювані ідентифікатори акаунтів в одному пакеті допустимі: перемагає останній.

Ліміти: 1000 акаунтів на запит, тіло 1 МіБ, account_id ≤ 256 символів, email ≤ 320, display_name ≤ 256, не більше 16 міток із ключами ≤ 64 і значеннями ≤ 256 символів.

Прикріплення полів після візиту

Браузер може надіслати лише те, що сторінка знає в момент рендеру, — номер замовлення, але ніколи не результат перевірки платежу чи щось інше, що з'ясовується пізніше. Цей маршрут закриває прогалину: знайдіть візит за полем, яке він уже має, і прикріпіть до нього додаткові поля на боці сервера.

curl -s -X POST "https://api.tracio.ai/v2/events/fields" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"},"fields":{"amount":"120.00"}}'

{ "updated": 1 }

• match знаходить візит за полем, яке він уже має, а не за request_id, у межах workspace і середовища вашого ключа.
• Вікно пошуку — 24 години. Старіший візит повертає 404 not_found — записуйте поле невдовзі після того, як результат з'ясувався.
• updated рахує різні візити. Значення більше за 1 лише тоді, коли ваш match влучає в кілька візитів, — пара ключ/значення, не унікальна для одного замовлення чи кошика. match, що влучає більше ніж у 100 подій, відхиляється з 400 invalid_request, а не застосовується до довільної підмножини.
• Поля, записані тут, з'являються в дашборді з позначкою server і мають пріоритет над значенням з тим самим ключем, записаним браузером.
• Відсутність збігу — це 404 not_found, а не порожній 200.

Ліміти збігаються з браузерним каналом: 50 полів за виклик, ключі ≤ 40 байтів, значення ≤ 500 байтів — байтів, а не символів, — набір символів ключа A-Za-z0-9_.:-, тіло 1 МіБ.

Видалення полів

Стирає користувацькі поля — але ніколи не сам візит. Використовуйте його для значень, які більше не потрібно тримати прив'язаними до візиту, наприклад суми замовлення. Уже надіслані вебхуки та вже зроблені вивантаження не змінюються.

# by request_id — clears every field on this one visit
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31"}'

# by match — clears "order_ref" from every visit currently holding "A-1029"
curl -s -X POST "https://api.tracio.ai/v2/events/fields/delete" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"match":{"key":"order_ref","value":"A-1029"}}'

{ "deleted": 1 }

• request_id і match взаємовиключні — якщо надіслати обидва або жодного, буде 400 invalid_request. match використовує те саме 24-годинне вікно і ту саму стелю в 100 подій, що й прикріплення.
• deleted рахує поля, видалені з візиту (за request_id), або візити, з яких поле було видалено (за match).
• Повторний виклик, коли видаляти вже нічого, повертає 404 not_found.

Списки workspace

Ті самі списки, якими ваші оператори керують у дашборді, доступні з вашого власного бек-офісу. Тип списку — це його дія щодо візиту, який збігся, — block, manual_review, challenge, allow, — а його режим вирішує, чи застосовується дія: observe лише рахує збіги, enforce застосовує її до guidance (вісь list). Списки та їхній режим створюються в дашборді; Data API читає списки, а також додає й видаляє елементи.

curl -s "https://api.tracio.ai/v2/lists" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

[
  {
    "id": "7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60",
    "name": "Chargeback accounts",
    "type": "block",
    "mode": "enforce",
    "entries_count": 128
  }
]

# ban an account for 30 days
curl -s -X POST "https://api.tracio.ai/v2/lists/7f3a9d2e-4c1b-4e8f-9a6d-1b2c3d4e5f60/entries" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
  -H "Content-Type: application/json" \
  -d '{"value":"usr_8412","value_type":"linked_id","ttl_minutes":43200}'

{
  "id": "02b4c8d1-6e7f-4a90-b1c2-d3e4f5a6b7c8",
  "value": "usr_8412",
  "value_type": "linked_id",
  "expires_at": "2026-10-19T12:00:00Z",
  "propagation": "immediate"
}

Видаліть елемент тим самим тілом за адресою POST /v2/lists/{list_id}/entries/delete; відповідь — { "removed": true, "propagation": "immediate" }.

• value_type — те, з чим зіставляється значення: linked_id, visitor_id, device_id, ip, cidr або country. Значення, яке не розбирається для свого типу, — це 400 invalid_request.
• Коли збігаються кілька списків, вирішує найконкретніший тип — linked_id → visitor_id → device_id → ip → cidr → country, — а всередині нього перемагає найсуворіша дія.
• ttl_minutes необов'язковий. Якщо його опустити, застосовується TTL списку за замовчуванням; якщо немає й його, елемент не спливає ніколи (expires_at дорівнює null). Повторне додавання елемента подовжує його.
• propagation повідомляє, коли зміна набуває чинності: immediate або ttl — приблизно протягом п'яти хвилин.
• Видалення значення, якого немає, — це 200 з removed: false; 404 зарезервовано за невідомим списком.

Домовленості щодо відповідей

Відсутнє поле означає «немає даних», а не нуль. Поля без значення опускаються цілком, а не надсилаються як 0, "" чи null: у зовсім нового відвідувача немає match_confidence, у чистого візиту немає antidetect_score та suspect_score. Єдиний навмисний виняток — bot.score: воно присутнє завжди, навіть коли дорівнює нулю. Читайте поля захисно.

Payload залежить від вашого тарифу. Доступ до API починається з Pro, і Pro отримує базову сесію — ідентифікатори, таймстамп, URL, IP, user agent, браузер, ОС, пристрій, гео, мережа, бот, ідентифікація та рішення — разом з identification.match_type, identification.match_confidence, bot.score, bot.type, bot.antidetect_score, gpu, network.proxy_detected, extensions, fields і account. Business та Enterprise додають geo.isp, network.asn, network.real_ip, decision.suspect_score, identification.drift_score, reasons, behavior, guidance, device_info, spoofing, os_environment, screen, locale, client_hints та environment. Поля рівня персони (person_id, reputation, linked_accounts_count, linked_visitors_count) зарезервовані за Business та Enterprise і з’являться, коли буде увімкнено шар персон, — сьогодні він працює в режимі спостереження, і ці поля не віддаються. Відсутність поля рівня Business на тарифі Pro — не помилка.

Внутрішнє на рівні сигналів не повертається ніколи, на жодному тарифі: імена окремих сигналів, їхні ваги, пороги за вердиктом, сирі значення сигналів і розкладка оцінок залишаються на нашому боці. Оцінка, яку можна зворотною розробкою звести до її вхідних даних, перестає бути захистом.

Помилки

Будь-який збій використовує один конверт:

{
  "error": {
    "code": "unauthorized",
    "message": "missing Authorization: Bearer <secret key>",
    "request_id": "8f14e45fceea167a5a36dedd"
  }
}

Цей request_id — не ідентифікатор візиту. Ім’я ділять два різні значення: всередині payload сесії request_id — це UUID візиту, той самий, який доставляє вебхук; у конверті помилки це 24-символьний ідентифікатор трасування, що випускається на кожен HTTP-виклик. Ідентифікатор трасування повертається ще й у заголовку X-Request-Id на кожній відповіді, успішній чи ні. Додайте його, коли звертаєтесь до підтримки, — саме за ним ми знаходимо ваш конкретний виклик.

Перевірки йдуть у фіксованому порядку — ключ, потім тариф, потім ліміти, — тож запит із поганим ключем завжди повідомляє спершу про ключ, а не про проблему з квотою. Дані іншого workspace не відрізнити від даних, яких не існує: вони дають 404, а не 403.

Два випадки 401 навмисно читаються по-різному: missing Authorization: Bearer <secret key> означає, що заголовок узагалі не надійшов, а invalid or revoked API key — що він надійшов і не збігся. 402 несе Data API requires the Pro plan or higher.

Повторюйте 429 і 503 зі зростаючою паузою; повторювати інші 4xx марно — вони означають, що виправити потрібно сам запит.

Ліміти частоти та квоти

Відповіді, для яких ключ розпізнано, несуть ваше поточне становище (відповіді 401 і 402 його не несуть, а Enterprise, у якого немає денної квоти, не отримує заголовків квоти):

• Короткі сплески дозволені: посекундний ліміт — це token bucket, який терпить до трикратного перевищення сталої швидкості, перш ніж починає відмовляти.
• Запит, відхилений за перевищення посекундної швидкості, не витрачає денну квоту, тож сплеск не може з’їсти бюджет дня.
• Ліміти Data API рахуються окремо від трафіку ідентифікації. Читання власної історії ніколи не витрачає ідентифікації, за які ви платите.

Наступні кроки

• Webhooks — отримуйте кожну ідентифікацію в момент, коли вона відбувається
• Зв’язування акаунтів — прив’яжіть власний ідентифікатор акаунта до пристрою
• Виявлення ботів — як формується вердикт щодо ботів
• Приватність і GDPR — обробка запитів суб’єктів даних