課金 API

コンソールを開かずに、自分のワークスペースの使用量とコストのデータを自分のシステムに取り込めます。課金キーは 読み取り専用の 資格情報で、1 つのワークスペースに限定されます - 課金データを読み取れるだけで、他には何もできません。

課金キーを作成する

1. 開く： Console → Billing API keys （ワークスペースの所有者のみ）。名前を付け、必要に応じて IP 許可リストで制限するか有効期限を設定し、キーをコピーします - キーは sk-syn-bill- で、表示されるのは一度だけです。
2. これを Bearer トークンとして、以下のエンドポイントを呼び出します。 同じページからいつでも取り消せます - 取り消すと即座に無効になり、ワークスペース内の他の何にも影響しません。
3. キーはその作成者に紐づいています。作成者がワークスペースの所有者でなくなると動作を停止し、 403 key_owner_not_authorized.

認証

すべての呼び出しには Authorization: Bearer sk-syn-bill-... を、下記の base URL に対して送ります。課金キーはこれらのエンドポイントでのみ機能し、これらのエンドポイントも課金キーのみを受け付けます - それ以外の組み合わせは 401 wrong_key_kind.

Authorization: Bearer sk-syn-bill-...

Base URL: https://synthorai.io/api/v1/billing

GET /usage - 集計使用量

GET /usage

時間単位または日単位で事前集計された行。請求書やダッシュボード向けです。時間ごとのロールアップに、前回の取り込み以降に書き込まれたリクエストを加えるため、直近のバケットが取り込み 1 周期分まるごと遅れることはありません。

各行では、api_key_id と api_key_name は group_by api_key を含む場合にのみ表示され、model も同様に model を含む場合にのみ表示されます。バケットにレイテンシのサンプルがない場合、avg_latency_ms は null になることがあります。

リクエスト例

curl "https://synthorai.io/api/v1/billing/usage?start=2026-09-01&end=2026-09-24&granularity=day" \
  -H "Authorization: Bearer sk-syn-bill-..."

レスポンス例

{
  "data": [
    {
      "bucket_start": "2026-09-23T00:00:00Z",
      "bucket_end": "2026-09-24T00:00:00Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "requests": 1280,
      "success_requests": 1265,
      "error_requests": 15,
      "errors_4xx": 12,
      "errors_429": 2,
      "errors_5xx": 1,
      "prompt_tokens": 512000,
      "completion_tokens": 98000,
      "cached_tokens": 210000,
      "cache_write_tokens": 8000,
      "reasoning_tokens": 4000,
      "cost_usd": 4.1732,
      "byok_list_price_usd": 0,
      "byok_requests": 0,
      "avg_latency_ms": 812,
      "final": true
    }
  ],
  "meta": {
    "generated_at": "2026-09-24T08:00:00Z",
    "data_complete_until": "2026-09-24T06:00:00Z",
    "timezone": "UTC",
    "currency": "USD",
    "next_cursor": null,
    "has_more": false
  }
}

GET /records - リクエスト単位の行

GET /records

リクエストごとに 1 行あり、自社データベースへの差分同期を想定しています。cursor で同期してください。時間で同期してはいけません。受け取った行は record_id で重複排除してください - 理由は下記の「時間の欠落を避ける」を参照してください。

リクエスト例

curl "https://synthorai.io/api/v1/billing/records?start=2026-09-24T00:00:00Z&limit=500" \
  -H "Authorization: Bearer sk-syn-bill-..."

レスポンス例

{
  "data": [
    {
      "record_id": "rec_8f2a91c4",
      "request_id": "req_9f3c2b1a",
      "recorded_at": "2026-09-24T05:58:31Z",
      "completed_at": "2026-09-24T05:58:29Z",
      "api_key_id": 42,
      "api_key_name": "prod-backend",
      "model": "claude-sonnet-5",
      "status": "success",
      "status_code": 200,
      "prompt_tokens": 812,
      "completion_tokens": 194,
      "cached_tokens": 512,
      "cache_write_tokens": 64,
      "cache_write_5m_tokens": 64,
      "cache_write_1h_tokens": 0,
      "cost_usd": 0.00412,
      "byok_list_price_usd": 0,
      "is_byok": false,
      "is_stream": true,
      "duration_ms": 1340,
      "ttft_ms": 210
    }
  ],
  "meta": {
    "next_cursor": "eyJvIjoiODgxNDA5MCJ9",
    "has_more": false,
    "window_final": true,
    "safe_until": "2026-09-24T05:58:31Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "data_complete_until": "2026-09-24T05:58:00Z"
  }
}

GET /records/export - ストリーミングエクスポート

GET /records/export

/records と同じフィルタを使い、改行区切りの JSON（application/x-ndjson）としてストリーミングされます - ページ分けされたリストではなく、大量のバックフィル向けに作られています。1 つのワークスペースで同時にストリーミングできるエクスポートは 1 つだけで、2 つ目は 429 too_many_concurrent_requests になります。

リクエスト例

curl -N "https://synthorai.io/api/v1/billing/records/export?cursor=eyJvIjoiODgxNDAzMiJ9" \
  -H "Authorization: Bearer sk-syn-bill-..."

レスポンス例

{"record_id":"rec_8f2a91c4","request_id":"req_9f3c2b1a","model":"claude-sonnet-5","status":"success","cost_usd":0.00412}
{"record_id":"rec_8f2a91c5","request_id":"req_9f3c2b1b","model":"claude-sonnet-5","status":"success","cost_usd":0.00398}
{"_meta":{"next_cursor":"eyJvIjoiODgxNDA5MSJ9","rows":2,"complete":true,"window_final":true,"generated_at":"2026-09-24T06:00:02Z"}}

ストリームの最後の行は _meta オブジェクトです：

GET /summary - 概算の統計と異常

GET /summary

合計、コスト上位のモデルとキー、対象範囲のエラー率に加えて、 anomalies リスト（high_error_rate、rate_limited、data_not_final、rollup_delayed）が付きます。それぞれに info または warning の重大度と、人が読める形式のメッセージが含まれます。確定していない範囲の数値は今後も変わる可能性があります - 詳細は下記を参照してください。

models_count と keys_count は top_models と top_keys の背後にある総数を示し、これらのリストはコスト上位最大 20 件までを掲載します。 end の 30 日前が、 start が省略された場合の範囲のデフォルトです。

リクエスト例

curl "https://synthorai.io/api/v1/billing/summary?start=2026-09-17&end=2026-09-24" \
  -H "Authorization: Bearer sk-syn-bill-..."

レスポンス例

{
  "data": {
    "totals": { "requests": 48210, "cost_usd": 132.55, "error_rate": 0.021 },
    "models_count": 6,
    "keys_count": 3,
    "top_models": [ { "model": "claude-sonnet-5", "cost_usd": 88.10, "byok_list_price_usd": 0 } ],
    "top_keys": [ { "api_key_id": 42, "api_key_name": "prod-backend", "cost_usd": 61.30, "byok_list_price_usd": 0 } ],
    "anomalies": [
      { "type": "data_not_final", "severity": "info", "message": "The last 2 hours of this range are not yet final." }
    ]
  },
  "meta": {
    "generated_at": "2026-09-24T06:00:02Z",
    "data_complete_until": "2026-09-24T04:00:00Z"
  }
}

GET /freshness - データの完全性

GET /freshness

返されるのは data_complete_until, latest_recorded_at, safe_until と pipeline_lag_seconds - 取得したばかりの範囲を確定済みとみなす前に、これをポーリングしてください。safe_until は呼び出し側が完全と信頼できる最新の recorded_at です。それより新しい行はまだ届いている可能性があります。

リクエスト例

curl "https://synthorai.io/api/v1/billing/freshness" \
  -H "Authorization: Bearer sk-syn-bill-..."

レスポンス例

{
  "data": {
    "data_complete_until": "2026-09-24T04:00:00Z",
    "latest_recorded_at": "2026-09-24T05:58:31Z",
    "safe_until": "2026-09-24T05:58:31Z",
    "pipeline_lag_seconds": 47
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z" }
}

GET /balance - ワークスペースで今使える残高

GET /balance

ワークスペースの現在の利用可能残高を返します。コンソールに表示される利用可能残高と同じ値です。ポーリング向けに設計されており、30〜60 秒ごとの確認で十分です。独自のレート制限を持つため、ポーリングがデータ系エンドポイントの枠を消費することはなく、残高がゼロでも応答します。

リクエスト例

curl "https://synthorai.io/api/v1/billing/balance" \
  -H "Authorization: Bearer sk-syn-bill-..."

レスポンス例

{
  "data": {
    "available_usd": 1284.37,
    "debt_usd": 0,
    "source": "live",
    "voucher": null,
    "scheduled_credits": [
      { "amount_usd": 250, "release_at": "2026-10-01T00:00:00Z" }
    ],
    "scheduled_credit_total_usd": 250
  },
  "meta": { "generated_at": "2026-09-24T06:00:02Z", "currency": "USD" }
}

エラー

すべてのエラーは {"error": {"type", "message", "hint"}}:

{
  "error": {
    "type": "range_too_large",
    "message": "the requested range exceeds this endpoint's cap",
    "hint": "narrow start/end to at most 31 days, or sync /records with a cursor instead"
  }
}

レート制限と上限

決して返されないもの： channel_id, upstream_request_id, usage_raw, other, content, ip_address, user_agent, cost_detail.

時間の欠落を避ける

リクエストが完了した後、非同期でログに書き込まれます（通常は数秒、バックログがあるとさらに長くなります）。/usage と /summary が参照する時間単位のロールアップはバッチで取り込まれます。直近の数時間は常に多少不完全です。/usage と /summary には前回の取り込み以降に書き込まれたリクエストも加わります（meta.live_tail が true）。ロールアップの遅れが大きすぎるときは加えず（meta.live_tail が false）、直近のバケットは不完全です。

data_complete_until は次の 2 つのうち早い方です：時間単位のロールアップの水位線から現在のパイプライン遅延を引いた値、またはまだロールアップされていない最も古いリクエスト - そこから 30 分の安全マージンを引き、時単位に切り下げます。

すべての /usage 行には final フラグがあります： true は、そのバケットの終了時刻が data_complete_until （/freshness の値）以前であるときに成立します。確定済みのバケットは二度と変わりません。

• 集計データ: (bucket_start, api_key_id, model) をキーとして、各行を自社ストアに upsert し、final: false のままのバケットは再取得してください。新しい合計から古い合計を引いて差分を求めることは絶対にしないでください。
• 生の行: cursor で同期してください。時間で同期してはいけません。next_cursor を保持し、次回の呼び出しではそこから再開してください。また、再送されたページが同じ行を再度届ける場合に備えて、受け取った行を record_id（各行に付く安定した不透明な id）で重複排除してください。書き込みからおよそ 5 分未満の行は保留されます - safe_until は最新の記録済み行の時刻から 5 分引いたものです - そのため、まだコミット中の行が既に渡したカーソル位置より前に紛れ込むことはなく、欠落は発生しません。リクエスト数を数えるときは、request_id の重複を除いて数えてください。
• 限定された範囲: cursor で同期する代わりに start/end の範囲を指定した場合、window_final が true のときにのみ完全であると信頼してください（end を指定し、それが safe_until 以前である場合にのみ true になります）。window_final が false の場合は、同じ範囲で後ほど再度呼び出すか、cursor による同期に切り替えてください。期間の開始は safe_until 以前である必要があります。それより後の開始は 400 start_too_recent（Retry-After ヘッダー付き）を返します。

推奨される連携方法

• 夜間の請求処理: 1 日 1 回、granularity=day で /usage を呼び出し、前回の実行で final: false だったバケットは再取得してください。
• リクエスト単位の詳細: 1 時間ごとに、保存済みの直前の next_cursor を cursor に設定して /records を呼び出し、has_more が true の間はページングを続け、受け取った行は record_id で重複排除してください。
• ダッシュボード: 表示中の範囲には /records を自前で集計するのではなく /summary を呼び出してください - 異常リストが既に含まれています。

課金データの読み取りではなく、通常の API キーをプログラムで発行・管理する必要がありますか？ Provisioning Keysをご覧ください。