Key 別の使用量を照会する

GET /api/open/v1/usage/keys

リクエストパラメーター

パラメーター	位置	型	必須	デフォルト	説明
start_timestamp	query	integer	いいえ	下記参照	開始時刻（含む）、unix 秒
end_timestamp	query	integer	いいえ	下記参照	終了時刻（含む）、unix 秒
group_by	query	string	いいえ	key_name	集計方法: key_name はリクエスト時点の Key 名で集計し、同名の Key は 1 行にまとめます。key_id は Key ごとに 1 行です
key_id	query	integer	いいえ	—	Key ID で絞り込みます。正の整数。複数指定する場合はパラメーターを繰り返すかカンマ区切りで指定します。他のユーザーの ID を指定すると空の結果だけが返ります
key_name	query	string	いいえ	—	Key 名の完全一致。複数指定する場合はパラメーターを繰り返します。名前にカンマを含められるためカンマ区切りは未対応
p	query	integer	いいえ	1	ページ番号。1–1000000
page_size	query	integer	いいえ	10	1 ページあたりの件数。1–1000
sort_by	query	string	いいえ	total_tokens	並べ替えキー: key_count（group_by=key_name の場合のみ）、prompt_tokens、completion_tokens、total_tokens、amount
order	query	string	いいえ	desc	並べ替え方向: asc または desc

時間範囲のルール:

• 両方とも省略: 直近 30 日間。
• start_timestamp のみ指定: そこから 30 日後まで。ただし現在時刻を超えません。
• end_timestamp のみ指定: そこから 30 日前まで。
• 範囲は最大 366 日です。

複数値パラメーターはそれぞれ最大 50 個までです。超えると 400 invalid_request を返します。明示的に指定した不正な p / page_size は 400 を返します。詳細は ページネーション を参照してください。

リクエスト例

curl "https://www.routeapi.ai/api/open/v1/usage/keys?start_timestamp=1726400000&end_timestamp=1729000000&sort_by=total_tokens&order=desc&p=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

レスポンス例

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_name": "bot",
        "key_count": 2,
        "prompt_tokens": 5000,
        "completion_tokens": 1000,
        "total_tokens": 6000,
        "amount": 0.20
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

group_by=key_id の場合は Key ごとに 1 行となり、key_id が含まれ、key_count は含まれません:

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_id": 12,
        "key_name": "bot",
        "prompt_tokens": 3000,
        "completion_tokens": 600,
        "total_tokens": 3600,
        "amount": 0.12
      },
      {
        "key_id": 15,
        "key_name": "bot",
        "prompt_tokens": 2000,
        "completion_tokens": 400,
        "total_tokens": 2400,
        "amount": 0.08
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

レスポンスフィールド

フィールド	型	説明
items[].key_id	integer	group_by=key_id の場合のみ。Key ID。API Key を取得する などのエンドポイントで使用できます。0 は API Key を経由しない使用量（プレイグラウンドなど）を表します
items[].key_name	string	group_by=key_name: リクエスト時点の Key 名。group_by=key_id: Key の現在の名前。Key が存在しない場合や key_id が 0 の場合は、その Key が期間内に最後にリクエストした時点の名前になります
items[].key_count	integer	group_by=key_name の場合のみ。この名前で期間内に消費があった異なる Key の数
items[].prompt_tokens	integer	この行の入力トークン総数
items[].completion_tokens	integer	この行の出力トークン総数
items[].total_tokens	integer	入力と出力のトークン合計
items[].amount	number	この行で消費した金額（返金を差し引いた後）。サイトの表示通貨、小数点以下 2 桁
total	integer	合計行数: group_by=key_name は名前の数、group_by=key_id は Key の数（key_id が 0 の行を含む）
page	integer	現在のページ番号
page_size	integer	実際に適用された 1 ページあたりの件数
start_timestamp	integer	実際に適用された開始時刻
end_timestamp	integer	実際に適用された終了時刻

エラー

HTTP	code	シナリオ
400	invalid_request	group_by、sort_by または order が不正、group_by=key_id の場合の sort_by=key_count、key_id が正の整数でない、タイムスタンプが数値でないか負の値、時間範囲が不正、ページネーションが不正、または複数値パラメーターが 50 個を超える
429	—	ユーザーごとの照会レート制限（デフォルト 30 回/分）を超過。レスポンスボディが空の場合があります

その他の共通エラーコードは プラットフォーム API のエラー を参照してください。

補足

• Key 名は重複する場合があります。group_by=key_name では同じ名前の Key が 1 行にまとめられるため、区別が必要な場合は group_by=key_id を使用してください。Key の値は返されません。
• まず sort_by で指定したフィールドで並べ、値が同じ場合は key_name（group_by=key_id の場合は key_id）の昇順で並ぶため、ページ送りは安定します。
• 履歴にはリクエスト時点の Key 名が保存され、名前を変更しても過去の記録は書き換えられません。そのため group_by=key_name では変更前後の使用量が 2 行に分かれます。key_name の絞り込みもリクエスト時の名前に一致しますが、group_by=key_id は現在の名前を返すため、両者は異なる場合があります。
• 各行の amount の合計は 使用量統計 の金額と一致します（四捨五入の誤差を除く）。
• 消費（課金）ログのみを集計し、失敗したリクエストは含まれません。
• トークン数は実数で、百万単位ではありません。
• 金額はサイトの表示通貨で表されます。残高を照会する を参照してください。
• 各行の amount は個別に四捨五入されるため、各行の合計と全体の金額が ±0.01 ずれる場合があります。
• Excel にエクスポートする場合は、同じ絞り込み条件でこのエンドポイントをページ送りし、items をまとめてください。
• このエンドポイントは 使用量統計、アカウントログ、ログのエクスポート、モデル別使用量 とユーザーごとの照会レート制限（デフォルト 30 回/分）を共有します。レート制限 を参照してください。