Data API

Data API（以前は本ページでServer APIとして記載されていたもの）は、TRACIOがお客様のワークスペースについてすでに収集した識別データを、バックエンドから読み取るためのものです: 訪問者の履歴、個々のセッション、そして短いウィンドウのベロシティカウンターです。いくつかのルートは書き込みも行います — アカウントのレコード、カスタムフィールド、リストのエントリ — これにより、お客様のバックエンドはTRACIOが把握している情報を補強できます。

これはWebhooksを置き換えるものではなく、補完するものです:

どちらのしくみもProプラン以上でご利用いただけます。

ベースURL

https://api.tracio.ai/v2

これはブラウザ用エンドポイント（edge.tracio.ai）とも、ダッシュボード （app.tracio.ai）とも別のホストです。3つはそれぞれ独立しています: ブラウザは 公開鍵でエッジと通信し、お客様のバックエンドはシークレットキーで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はサーバー間通信専用です。 CORSヘッダーは意図的に返されないため、 ブラウザから呼び出すことはできません — これがシークレットキーをクライアント側の コードから遠ざけています。シークレットキーをブラウザへ配布しないでください。

シークレットキーの取得

ダッシュボードのAPI Keysで、secretタイプを選んで作成します。

• 完全なキーは、作成時に一度だけ表示されます。当社側にはハッシュしか保存されない ため、紛失したキーを復元することはできません — 代わりにローテーションしてください。
• シークレットキーは tracio_sk_ に43文字が続く形で、合計53文字です。ダッシュボードは 先頭の数文字で一覧表示するため、キーを見分けられます。
• シークレットキーにはProプラン以上が必要です。ブラウザエージェントが使う公開鍵は、 これとは別の、秘密ではない40文字の値です。
• キーは環境に紐付いています: 本番のキーからはステージングの訪問者は見えません — レスポンスは 404 で、存在しないデータの場合とまったく同じです。

シークレットキーのローテーション

ローテーションを行うと新しいキーが発行され、古いキーは7日間動作し続けるため、 ダウンタイムなしで切り替えられます。新しいキーをデプロイし、トラフィックが移ったことを 確認して、古いキーを失効させてください。公開鍵はローテーションできません — 秘密では なく、設計上ページのソースに見えるものだからです。

エンドポイント

同じキーとホストで判定APIも提供されており、いずれも snake_case です:

これらの結果はWebhookイベントとしても届きます: transaction_state_changed、login_risk、trusted_device_enrolled、 trusted_device_revoked、affiliate_threshold_crossed。

末尾のスラッシュは受け入れられ、無視されます。未知のパスや誤ったメソッドは、他と同じ JSONのエラーエンベロープを返します — HTMLやプレーンテキストのページが返ることは 決してありません。

時間ウィンドウ

すべての読み取りは時間ウィンドウで区切られ、2つの省略可能なクエリパラメーターで 制御します:

• to に日付だけを指定した場合、その日1日が丸ごと含まれます。
• それ以外は 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"

レスポンスは集計履歴を運び、最新セッションを埋め込んでいるため、一般的なケースでは 2回ではなく1回のリクエストで済みます:

{
  "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"
  }
}

保持期間内にデータがない訪問者には、visitor not found in the retention window という メッセージとともに 404 not_found が返ります — これは統合側の誤りではなく、その 訪問者が新規であるか、保持期間を過ぎたことを意味します。

判定フィールド

セッションは2つの判定を運び、それぞれ別の問いに答えます — クライアントが自動化されて いたかどうかと、リスクエンジンが全体として下した結論です:

bot.score と decision.risk_score はどちらも 0..100 のスケールです。Business以上 では、guidance がそれらを allow → challenge → review → deny というラダー上の シナリオごとの推奨に変換します — 各段の意味については Guidanceを参照してください。 値とスケールは同じ訪問のv3 Webhook本文と一致し、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から取得したブラウザとOSに加えて、セッションは訪問者のブラウザがマシン について報告する内容を、当社側でサニタイズしたうえで保持します。訪問がそうした データを運ばなかった場合、いずれのフィールドも存在しないため、すべて任意として扱って ください。

ブラウザ拡張機能

extensions は、その訪問中に検出されたブラウザ拡張機能を列挙します — Pro以上です。 エントリはそれぞれオブジェクトです:

検出結果は、当社の信頼性チェックを通過したうえでのみ報告されます — すべての探索に「インストール済み」と答える環境や、12件を超える名前のまとまりは、信頼できないものとして破棄されます。したがって、空のリストやリストの欠如は「インストールされている拡張機能はない」ではなく、「確認できたものがない」を意味します。これは在庫目録ではなく、証拠として読んでください。

カスタムフィールド

fields には、お使いのインテグレーションが訪問に付加したカスタムのキーと値のペア（注文の参照番号、プラン名、決済の結果など）が入ります。キーと値は常に文字列で、付加した数値や真偽値はテキスト形式で返されます。セッションのほかの部分と同様に、API を利用できるすべてのプラン（Pro以上）でご利用いただけます。訪問にフィールドがない場合、この項目は含まれません。

fields は訪問時にコピーされるのではなく、すべてのリクエストでその時点の内容が読み取られます。訪問の後で付加されたフィールド（訪問後にフィールドを付加するを参照）もここに表示されるため、同じ訪問でも fields にはWebhookが配信した内容より多くの項目が含まれることがあります。

氏名、メールアドレス、電話番号などの個人データはカスタムフィールドに入れないでください。代わりに、お客様ご自身のシステムで照合できる参照を付加し、そのアカウントが誰であるかはアカウントのレコード（下記）として送信してください。

アカウントのレコード

account は、訪問の背後にあるアカウントについてのお客様のレコードです — その account_id について POST /v2/accounts/metadata で最後に送信した内容です:

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

レコードはすべてのリクエストでその時点の内容が読み取られるため、名前の変更は過去の訪問にも反映されます: このブロックは訪問時点ではなく、現在のアカウントの姿を表します。APIアクセスを含むすべてのプラン（Pro以上）でご利用いただけます。レコードとともに送信したラベルは返されません。

訪問に紐付いたアカウントがない場合、そのアカウントのレコードがない場合（または空の値を送信して消去した場合）、そしてまれにレコードを読み取れなかった場合、このブロックは存在しません: その場合もリクエストを失敗させずにセッションを完全な形で返すため、ブロックがないことは「このアカウントにはメールアドレスがない」ではなく「不明」として扱ってください。Webhookはこのブロックを運びません。

単一のセッションを取得する

直近の1件:

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

これはセッションオブジェクトをそのまま返します — 配列でもなく、エンベロープに包まれても いません。ウィンドウ内にセッションがない訪問者には、 no sessions for this visitor in the retention window とともに 404 not_found が 返ります。

あるいは、Webhookのペイロードにも現れる識別子である request_id で取得します:

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 Webhookでも届きます。

訂正された訪問について得られる回答

1回の訪問がWebhookで複数回配信されることがあります: まず primary、続いて遅いシグナルや行動の証拠が届くにつれて late または correction — そして後のフェーズが先の判定を覆すことがあります。Data APIは primary のレコードから回答します。 後のフェーズはそこにマージされないため、訂正された訪問については最後のWebhookのほうが新しい回答です。訪問から数分後に対処する場合は、ここで新たに読み取るよりも、最後に受け取ったフェーズを優先してください。

逆向きに働くものが1つあります: ある訪問でアカウント乗っ取りの検知器が発火すると、ここでの guidance はそれを反映しますが、同じ訪問の identification Webhookの本文はその軸を運びません — それは専用の account_takeover の配信に乗ります。

ベロシティ

ベロシティは「この訪問者が最近どれだけ活動しているか」に答えます — クレデンシャル スタッフィング、カードテスティング、大量アカウント作成に共通する形です。

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 として渡すIDを通じてだけです — usr_8412 のような不透明な文字列です。人が読めるラベルを一度送信すれば、そのアカウントを表示するダッシュボードの画面はすべて、生のIDの代わりに名前やメールアドレスを表示し、セッションオブジェクトもそれらを 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 ではありません。 ここで送信したメールアドレスや名前は、お客様のワークスペースのアカウントのレコードにのみ保存されます: 訪問単位では保存されず、ページにも書き込まれず、1回の送信でそのアカウントのすべての訪問が更新されます。
• スコープはキーのワークスペースと環境です。 ステージングのキーが、同じアカウントIDについて本番のキーが書き込んだ内容を上書きすることはありません。
• すべての送信は部分更新ではなく、完全な上書きです。 省略したフィールドは空として保存されます — 毎回レコード全体を送信してください。値を消去する方法も同じです。
• 未知のフィールドは 400 invalid_request で拒否され、不正なエントリが1件あるとバッチ全体が拒否されます — エラーはその位置を示します。1つのバッチ内でアカウントIDが重複していても問題ありません: 最後のものが優先されます。

上限: 1リクエストあたり1000アカウント、本文1 MiB、account_id ≤ 256文字、email ≤ 320、display_name ≤ 256、ラベルは最大16個でキー ≤ 64、値 ≤ 256文字。

訪問後にフィールドを付加する

ブラウザが送信できるのは、レンダリング時点でページが知っている内容だけです — 注文IDは送れても、決済チェックの結果や後から確定するものは送れません。このルートはその隙間を埋めます: 訪問がすでに持っているフィールドで訪問を見つけ、サーバー側からフィールドを追加で付加します。

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 ではありません。範囲はキーのワークスペースと環境の中です。
• 検索ウィンドウは24時間です。 それより古い訪問には 404 not_found が返ります — 結果が確定したら早めにフィールドを書き込んでください。
• updated は異なる訪問の数を数えます。 1を超えるのは、match が複数の訪問に一致した場合だけです — 1つの注文やカートに固有ではないキーと値のペアです。100件を超えるイベントに一致する match は、任意の一部に適用されるのではなく、400 invalid_request で拒否されます。
• ここで書き込んだフィールドは、ダッシュボードで server のタグ付きで表示され、ブラウザが書き込んだ同じキーの値より優先されます。
• 一致なしは 404 not_found です。空の 200 ではありません。

上限はブラウザのチャネルと同じです: 1回の呼び出しで50フィールド、キー ≤ 40バイト、値 ≤ 500バイト — 文字数ではなくバイト数 — キーの文字セットは A-Za-z0-9_.:-、本文1 MiB。

フィールドの削除

カスタムフィールドを消去します — 訪問そのものは決して消去しません。注文の合計額のように、もう訪問に付加しておく必要のない値に使ってください。すでに送信されたWebhookや、すでに取得されたエクスポートは変更されません。

# request_id で指定 — この1回の訪問のすべてのフィールドを消去
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"}'

# match で指定 — 現在 "A-1029" を持つすべての訪問から "order_ref" を消去
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 が返ります。

ワークスペースのリスト

オペレーターがダッシュボードで管理しているのと同じリストに、お客様ご自身のバックオフィスからアクセスできます。リストのタイプは、一致した訪問に対するアクションです — 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
  }
]

# アカウントを30日間禁止する
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 — 約5分以内です。
• 存在しない値の削除は 200 で removed: false です。404 は未知のリストのために予約されています。

レスポンスの規約

フィールドがないことは「データなし」を意味し、ゼロを意味することはありません。 値のないフィールドは 0、""、null として送られるのではなく、完全に省略されます: まったく新しい訪問者には match_confidence がなく、問題のない訪問には antidetect_score も suspect_score もありません。意図的な唯一の例外は bot.score で、 これはゼロのときでも常に存在します。フィールドは防御的に読み取ってください。

ペイロードはご利用のプランによって変わります。 APIアクセスはProから利用でき、Proでは基本のセッションが得られます — 識別子、タイムスタンプ、URL、IP、user agent、ブラウザ、OS、デバイス、位置情報、ネットワーク、ボット、識別、判定 — それに加えて 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向けに予約されており、人レイヤーが有効化されれば現れます — 現在は観測モードで稼働しており、これらのフィールドは配信されません。ProプランでBusinessのフィールドがないことはエラーではありません。

シグナルレベルの内部情報は、どのプランでも返されません: 個々のシグナル名、その 重み、判定の背後にあるしきい値、生のシグナル値、スコアの内訳は当社側にとどまります。 入力に逆算できてしまうスコアは、防御としての有用性を失います。

エラー

すべての失敗は1つのエンベロープを使います:

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

この request_id は訪問識別子ではありません。同じ名前を2つの異なる値が共有して います: セッションのペイロード内では request_id は訪問のUUIDで、Webhookが配信するのと 同じものです。エラーエンベロープ内では、HTTP呼び出しごとに発行される24文字のトレース 識別子です。トレース識別子は、成功・失敗を問わずすべてのレスポンスの X-Request-Id ヘッダーでも返されます。サポートへ問い合わせる際には添えてください — それによって 当社はお客様の呼び出しを正確に特定できます。

チェックは決まった順序で実行されます — キー、次にプラン、そして上限 — そのため、不正な キーを持つリクエストは常にまずキーの問題を報告し、クォータの問題を報告することは ありません。別のワークスペースのデータは、存在しないデータと区別がつきません: 403 ではなく 404 になります。

2つの 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 のレスポンスは運ばず、1日あたりのクォータがないEnterpriseにはクォータのヘッダーは付きません）:

• 短いバーストは許容されます: 秒あたりの制限はトークンバケットで、拒否を始めるまでに 持続レートの3倍までを許容します。
• 秒あたりのレート超過で拒否されたリクエストは、1日あたりのクォータを消費しません。 そのため、バーストがその日の予算を食い潰すことはありません。
• Data APIの上限は、識別トラフィックとは別に数えられます。自分の履歴を読み取っても、 お支払いいただいている識別回数が消費されることはありません。

次のステップ

• Webhooks — 識別が起きるたびに受け取る
• アカウント連携 — 自社のアカウントIDをデバイスに紐付ける
• ボット検知 — ボット判定がどのように生成されるか
• プライバシーとGDPR — データ主体の請求への対応