> ## Documentation Index > Fetch the complete documentation index at: https://docs.toapis.com/llms.txt > Use this file to discover all available pages before exploring further. # トークン使用量の照会 > すべての API Key のリクエスト単位の Token 消費量と費用を照会する * **すべての** API Key のリクエスト単位の Token 消費量と費用を照会。単一 Key での絞り込みも可能 * 入力・出力・キャッシュヒットの Token を個別に集計 * サマリーエンドポイントで Key ごとの合計を取得 * カーソルベースのページネーション。期間は最長 31 日 これらのエンドポイントは課金ログを読み取り、課金対象の各リクエストの Token 内訳と費用、および Key ごとの集計を返します。単一 Key の合計残高しか返さない [トークン残高の照会](https://docs.toapis.com/docs/ja/api-reference/account/token-balance.md) を補完するものです。 ## 認証 **Authorization** `string` *required* このエンドポイントは `sk-` API Key ではなく**ユーザーアカウント**として認証します。 1. [アカウント設定ページ](https://toapis.com/dashboard/settings) を開き、「システムアクセストークン」カードで **生成** をクリックしてアクセストークンを発行します（`sk-` キーではありません）。再生成すると以前のトークンは無効になります。 2. アクセストークンとユーザー ID を一緒に送信します： ``` Authorization: Bearer YOUR_ACCESS_TOKEN X-User-Id: YOUR_USER_ID ``` 数値のユーザー ID は同じ設定ページに表示されます。 **X-User-Id** `string` *required* 数値のユーザー ID。アクセストークンと併せて必須です。 ## エンドポイント ``` GET /api/usage/tokens/requests # リクエスト単位の明細 GET /api/usage/tokens/summary # Key ごとの集計 ``` ## クエリパラメータ 両エンドポイントで同一のパラメータを受け付けます。未定義または重複したパラメータは `422` で拒否されます。 **start\_timestamp** `integer` *required* 期間の開始。Unix 秒タイムスタンプ（その時刻を含む）。 **end\_timestamp** `integer` *required* 期間の終了。Unix 秒タイムスタンプ（その時刻を含まない）。`start_timestamp` より後である必要があり、期間は最長 31 日です。 **token\_id** `integer` 任意。数値のトークン ID で単一の API Key に絞り込みます。省略時はすべての Key が対象です。 **page\_size** `integer` (default: 50) 1 ページあたりの行数。`1`–`100`。 **cursor** `string` 前回のレスポンスの `meta.next_cursor` に返されたページネーションカーソル。発行元と同じエンドポイント・期間・`token_id` フィルターでのみ有効です。 ## レスポンス `GET /api/usage/tokens/requests` は課金対象リクエストごとに 1 行を、新しい順に返します。 **log\_id** `integer` リクエストに対応する内部ログ ID。レスポンス内で一意です。 **created\_at** `integer` リクエストが課金された時刻。Unix 秒タイムスタンプ。 **token\_id** `integer` リクエストを行った API Key の ID。 **token\_name** `string` API Key の名前。 **model\_name** `string` リクエストを処理したモデル。 **task\_id** `string` 非同期リクエスト（画像/動画生成）のタスク ID。同期リクエストでは空。 **prompt\_tokens** `integer` 課金された入力 Token 数。 **completion\_tokens** `integer` 課金された出力 Token 数。 **cache\_tokens** `integer | null` キャッシュから読み取られた入力 Token 数（キャッシュヒット）。上流が報告しない場合は `null`。 **cache\_creation\_tokens** `integer | null` キャッシュに書き込まれた Token 数。報告されない場合は `null`。 **reported\_total\_tokens** `integer | null` 上流プロバイダーが報告した合計 Token 数（利用可能な場合）。 **total\_tokens** `integer` `prompt_tokens + completion_tokens`。 **billing\_phase** `string` `pre_consumed`、`settled`、または詳細な課金メタデータが存在しない古いログでは `unknown`。 **quota** `integer` 消費されたクォータ（プラットフォーム内部単位）。 **cost\_usd** `string` 米ドル換算の費用。`quota / quota_per_usd` で計算（`meta` 参照）。精度保持のため文字列で返します。 `GET /api/usage/tokens/summary` は API Key ごとに 1 行を、`token_id` 昇順で返します。 **token\_id** `integer` API Key ID。 **request\_count** `integer` 期間内の課金リクエスト数。 **prompt\_tokens** `integer` この Key の入力 Token 合計。 **completion\_tokens** `integer` この Key の出力 Token 合計。 **total\_tokens** `integer` `prompt_tokens + completion_tokens`。 **quota** `integer` この Key が消費したクォータ合計。 **cost\_usd** `string` この Key の米ドル費用合計。 ### Meta **meta.has\_more** `boolean` 次のページが存在するかどうか。 **meta.next\_cursor** `string` `cursor` として渡すと次ページを取得。`has_more` が `false` の場合は空。 **meta.quota\_per\_usd** `string` `cost_usd` 換算に使用した 1 米ドルあたりの内部クォータ単位数。 **meta.consume\_logging\_enabled** `boolean` 消費ログが有効かどうか。`false` の場合、レスポンスが空になることがあります。 **meta.refunds\_included** `boolean` 現時点では常に `false`。返金分は差し引かれません。 ```bash cURL — リクエスト明細 theme={null} curl --request GET \ --url 'https://toapis.com/api/usage/tokens/requests?start_timestamp=1759708800&end_timestamp=1760313600&page_size=100' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-User-Id: YOUR_USER_ID' ``` ```bash cURL — 単一 Key の集計 theme={null} curl --request GET \ --url 'https://toapis.com/api/usage/tokens/summary?start_timestamp=1759708800&end_timestamp=1760313600&token_id=45' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'X-User-Id: YOUR_USER_ID' ``` ```python Python — 全ページを取得 theme={null} import requests API_BASE = 'https://toapis.com' headers = { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN', 'X-User-Id': 'YOUR_USER_ID', } params = { 'start_timestamp': 1759708800, 'end_timestamp': 1760313600, 'page_size': 100, } while True: r = requests.get(f'{API_BASE}/api/usage/tokens/requests', headers=headers, params=params) body = r.json() for row in body['data']: print(row['created_at'], row['token_name'], row['model_name'], row['prompt_tokens'], row['completion_tokens'], row['cache_tokens'], row['cost_usd']) if not body['meta']['has_more']: break params['cursor'] = body['meta']['next_cursor'] ``` ```json 200 - requests theme={null} { "success": true, "data": [ { "log_id": 10241024, "created_at": 1760001234, "token_id": 45, "token_name": "prod-backend", "model_name": "gpt-5.1", "task_id": "", "prompt_tokens": 148320, "completion_tokens": 2198, "cache_tokens": 96000, "cache_creation_tokens": 0, "reported_total_tokens": 150518, "total_tokens": 150518, "billing_phase": "settled", "quota": 7839, "cost_usd": "0.015678" } ], "meta": { "start_timestamp": 1759708800, "end_timestamp": 1760313600, "page_size": 100, "has_more": true, "next_cursor": "eyJraW5kIjoicmVxdWVzdHMiLC4uLn0", "cost_basis": "consume_log_quota", "currency": "USD", "quota_per_usd": "500000", "consume_logging_enabled": true, "refunds_included": false, "total_tokens_basis": "logged_prompt_plus_completion" } } ``` ```json 200 - summary theme={null} { "success": true, "data": [ { "token_id": 45, "request_count": 87, "prompt_tokens": 3200400, "completion_tokens": 150220, "total_tokens": 3350620, "quota": 401234, "cost_usd": "0.802468" } ], "meta": { "start_timestamp": 1759708800, "end_timestamp": 1760313600, "page_size": 50, "has_more": false, "next_cursor": "", "cost_basis": "consume_log_quota", "currency": "USD", "quota_per_usd": "500000", "consume_logging_enabled": true, "refunds_included": false, "total_tokens_basis": "logged_prompt_plus_completion" } } ``` ```json 401 theme={null} { "success": false, "error": { "code": "unauthorized", "message": "user authentication is required" } } ``` ```json 422 theme={null} { "success": false, "error": { "code": "invalid_query", "message": "time range must be positive and no longer than 31 days" } } ``` ```json 503 theme={null} { "success": false, "error": { "code": "query_timeout", "message": "usage query exceeded the time limit; use a shorter time range" } } ``` ## 注意事項 * **課金対象**のリクエストのみが一覧に含まれます。課金されなかった失敗リクエストは表示されず、リクエスト単位の成功フラグも返されません。 * 費用は課金時に記録されたクォータに基づき、現在のカタログ価格で再計算されません。返金も差し引かれません。 * これらのエンドポイントは生の API Key、チャネル、IP アドレス、リクエスト/レスポンス内容を公開しません。 * `cursor` はエンドポイント・期間・`token_id` フィルターに紐付いています。異なるクエリ間で再利用しないでください。 * クエリには短いタイムアウトがあります。`query_timeout` を受け取った場合は期間を短くして再試行してください。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.