Server API

Server APIは、TRACIOがお客様のワークスペースについてすでに収集した識別データを、 バックエンドから読み取るためのものです: 訪問者の履歴、個々のセッション、そして 短いウィンドウのベロシティカウンターです。

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

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

ベースURL

https://api.tracio.ai/v1

これはブラウザ用エンドポイント（edge.tracio.ai）とも、ダッシュボード （app.tracio.ai）とも別のホストです。3つはそれぞれ独立しています: ブラウザは 公開鍵でエッジと通信し、お客様のバックエンドはシークレットキーでServer API と通信します。

認証

すべてのリクエストは、シークレットキーをbearerトークンとして運びます:

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

Server APIはサーバー間通信専用です。 CORSヘッダーは意図的に返されないため、 ブラウザから呼び出すことはできません — これがシークレットキーをクライアント側の コードから遠ざけています。シークレットキーをブラウザへ配布しないでください。

シークレットキーの取得

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

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

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

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

エンドポイント

すべてのルートは GET です。Server APIに書き込み操作はありません: データを読み取る だけで、設定はダッシュボードにあります。

末尾のスラッシュは受け入れられ、無視されます。未知のパスや誤ったメソッドは、他と同じ 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/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y"

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

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-05-02T10:11:12Z",
  "lastSeenAt": "2026-07-25T08:00:00Z",
  "visits": 42,
  "incognitoVisits": 3,
  "uniqueIps": 5,
  "uniqueCountries": 2,
  "browsers": ["Chrome"],
  "os": ["macOS"],
  "devices": ["desktop"],
  "risk": {
    "maxRiskScore": 63,
    "avgBotScore": 12.5,
    "botSessions": 7,
    "lastDecision": "real"
  },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true,
    "lastIsp": "Deutsche Telekom"
  },
  "lastSession": {
    "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
    "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
    "accountId": "user_8842",
    "timestamp": "2026-07-25T08:00:00Z",
    "tag": "checkout",
    "url": "https://shop.example.com/checkout",
    "ip": "203.0.113.42",
    "userAgent": "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",
    "geo": {
      "country": "DE",
      "city": "Berlin",
      "timezone": "Europe/Berlin",
      "isp": "Deutsche Telekom"
    },
    "network": {
      "vpn": false,
      "proxy": false,
      "tor": false,
      "datacenter": false,
      "asn": 3320
    },
    "bot": { "result": "human", "score": 4.5, "antidetectScore": 2.1 },
    "identification": {
      "confidence": 0.97,
      "incognito": false,
      "matchType": "exact",
      "matchConfidence": 0.99
    },
    "decision": { "action": "real", "riskScore": 12 }
  },
  "meta": {
    "plan": "business",
    "retentionDays": 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.riskScore はどちらも 0..100 のスケールです。Business以上 では、guidance がそれらを allow → challenge → review → deny というラダー上の シナリオごとの推奨に変換します — 各段の意味については Guidanceを参照してください。

訪問者のセッションを一覧する

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

セッションは新しいものから順に返されます:

{
  "items": [
    {
      "requestId": "9c1f6a2e-3b7d-4c58-a1e2-6f0d8b4a7c31",
      "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
      "timestamp": "2026-07-25T08:00:00Z"
    }
  ],
  "nextCursor": "MTcyMTg5NDQwMDAwMDphYmMxMjM",
  "hasMore": true,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-04-26T00:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

ページネーション

ページ送りはカーソル方式です。page や offset のパラメーターはありません: 受け取った nextCursor を cursor として渡し、hasMore が true である間は続けてください。

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

  do {
    const url = new URL(`https://api.tracio.ai/v1/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(`Server API: ${res.status}`)

    const page = await res.json()
    sessions.push(...page.items)
    cursor = page.nextCursor
  } while (cursor)

  return sessions
}

カーソルは不透明なものとして扱ってください — その中身は実装の詳細であり、変更される 可能性があります。編集されたカーソルは 400 invalid_request と malformed cursor というメッセージで拒否されます。

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

直近の1件:

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

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

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

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

ここでの visitorId は省略可能ですが、分かっている場合に渡すと検索が大幅に速く なります。

ベロシティ

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

curl -H "Authorization: Bearer tracio_sk_XXXX...XXXX" \
     "https://api.tracio.ai/v1/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,
  "uniqueIps": 9,
  "uniqueCountries": 3,
  "uniqueAccounts": 12,
  "botEvents": 4,
  "meta": {
    "plan": "business",
    "retentionDays": 90,
    "from": "2026-07-25T11:00:00Z",
    "to": "2026-07-25T12:00:00Z"
  }
}

uniqueAccounts は、このデバイスについて送信された異なる linkedId の値を数えます — アカウント連携を参照してください。botEvents はBusiness以上 です。

レスポンスの規約

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

ペイロードはご利用のプランによって変わります。 APIアクセスを含むすべてのプランで、 基本のセッションが得られます — 各識別子、タイムスタンプ、URL、IP、user agent、 ブラウザ、OS、デバイス、位置情報、ネットワーク、ボット、識別、判定です。Proでは identification.matchType、identification.matchConfidence、bot.antidetectScore が加わります。BusinessとEnterpriseでは geo.isp、network.asn、 decision.suspectScore、identification.driftScore、reasons、behavior、 guidance、deviceInfo と、人単位のフィールド（personId、reputation、 linkedAccountsCount、linkedVisitorsCount）が加わります。ProプランでBusinessの フィールドがないことはエラーではありません。

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

エラー

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

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

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

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

2つの 401 は意図的に異なる文面になっています: missing Authorization: Bearer <secret key> はヘッダーがそもそも届かなかったことを、invalid or revoked API key は届いたが一致 しなかったことを意味します。402 は Data API requires the Pro plan or higher を 運びます。

レート制限とクォータ

認証済みのレスポンスはすべて、現在の状況を運びます:

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

次のステップ

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