> ## 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 の合計残高しか返さない [トークン残高の照会](/docs/ja/api-reference/account/token-balance) を補完するものです。 ## 認証このエンドポイントは `sk-` API Key ではなく**ユーザーアカウント**として認証します。 1. [アカウント設定ページ](https://toapis.com/dashboard/settings) を開き、「システムアクセストークン」カードで **生成** をクリックしてアクセストークンを発行します（`sk-` キーではありません）。再生成すると以前のトークンは無効になります。 2. アクセストークンとユーザー ID を一緒に送信します： ``` Authorization: Bearer YOUR_ACCESS_TOKEN X-User-Id: YOUR_USER_ID ``` 数値のユーザー ID は同じ設定ページに表示されます。数値のユーザー ID。アクセストークンと併せて必須です。 ## エンドポイント ``` GET /api/usage/tokens/requests # リクエスト単位の明細 GET /api/usage/tokens/summary # Key ごとの集計 ``` ## クエリパラメータ両エンドポイントで同一のパラメータを受け付けます。未定義または重複したパラメータは `422` で拒否されます。期間の開始。Unix 秒タイムスタンプ（その時刻を含む）。期間の終了。Unix 秒タイムスタンプ（その時刻を含まない）。`start_timestamp` より後である必要があり、期間は最長 31 日です。任意。数値のトークン ID で単一の API Key に絞り込みます。省略時はすべての Key が対象です。 1 ページあたりの行数。`1`–`100`。前回のレスポンスの `meta.next_cursor` に返されたページネーションカーソル。発行元と同じエンドポイント・期間・`token_id` フィルターでのみ有効です。 ## レスポンス `GET /api/usage/tokens/requests` は課金対象リクエストごとに 1 行を、新しい順に返します。リクエストに対応する内部ログ ID。レスポンス内で一意です。リクエストが課金された時刻。Unix 秒タイムスタンプ。リクエストを行った API Key の ID。 API Key の名前。リクエストを処理したモデル。非同期リクエスト（画像/動画生成）のタスク ID。同期リクエストでは空。課金された入力 Token 数。課金された出力 Token 数。キャッシュから読み取られた入力 Token 数（キャッシュヒット）。上流が報告しない場合は `null`。キャッシュに書き込まれた Token 数。報告されない場合は `null`。上流プロバイダーが報告した合計 Token 数（利用可能な場合）。 `prompt_tokens + completion_tokens`。 `pre_consumed`、`settled`、または詳細な課金メタデータが存在しない古いログでは `unknown`。消費されたクォータ（プラットフォーム内部単位）。米ドル換算の費用。`quota / quota_per_usd` で計算（`meta` 参照）。精度保持のため文字列で返します。 `GET /api/usage/tokens/summary` は API Key ごとに 1 行を、`token_id` 昇順で返します。 API Key ID。期間内の課金リクエスト数。この Key の入力 Token 合計。この Key の出力 Token 合計。 `prompt_tokens + completion_tokens`。この Key が消費したクォータ合計。この Key の米ドル費用合計。 ### Meta 次のページが存在するかどうか。 `cursor` として渡すと次ページを取得。`has_more` が `false` の場合は空。 `cost_usd` 換算に使用した 1 米ドルあたりの内部クォータ単位数。消費ログが有効かどうか。`false` の場合、レスポンスが空になることがあります。現時点では常に `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.