> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 消費用量の照会
> - 指定期間の消費金額と呼び出し統計を照会
- モデルで絞り込み、モデル別・暦日別に集計
- 現在の API Key またはアカウント全体の消費を照会
- 米ドル金額、クレジット、呼び出し回数、トークン用量を返却
API Key で指定期間の消費金額を照会し、モデルで絞り込み、モデル別・暦日別または両方で集計できます。集計結果を直接返すため、タスクの作成や状態のポーリングは不要です。
```bash cURL theme={null}
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer ' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'group_by=model'
```
```python Python theme={null}
import requests
response = requests.get(
"https://api.apimart.ai/v1/usage",
headers={"Authorization": "Bearer "},
params={
"start": "2026-09-01T00:00:00+08:00",
"end": "2026-09-08T00:00:00+08:00",
"group_by": "model",
},
timeout=30,
)
payload = response.json()
if not response.ok or not payload.get("success"):
message = payload.get("error", {}).get("message", "用量の照会に失敗しました")
raise RuntimeError(f"HTTP {response.status_code}: {message}")
print(payload["data"]["total"])
print(payload["data"]["items"])
```
```javascript JavaScript theme={null}
const url = new URL("https://api.apimart.ai/v1/usage");
url.search = new URLSearchParams({
start: "2026-09-01T00:00:00+08:00",
end: "2026-09-08T00:00:00+08:00",
group_by: "model",
}).toString();
const response = await fetch(url, {
headers: { Authorization: "Bearer " },
});
const payload = await response.json();
if (!response.ok || !payload.success) {
throw new Error(
`HTTP ${response.status}: ${payload.error?.message ?? "用量の照会に失敗しました"}`,
);
}
console.log(payload.data.total);
console.log(payload.data.items);
```
```json 200 theme={null}
{
"success": true,
"data": {
"scope": "key",
"start": 1788192000,
"end": 1788796800,
"tz": "Asia/Shanghai",
"group_by": "model",
"total": {
"amount_usd": 12.3456,
"credits": 123.456,
"requests": 1834,
"prompt_tokens": 902311,
"completion_tokens": 215044
},
"items": [
{
"model": "gpt-5.6-luna",
"amount_usd": 9.1271,
"credits": 91.271,
"requests": 1520,
"prompt_tokens": 880120,
"completion_tokens": 201300
},
{
"model": "sora-2",
"amount_usd": 3.2185,
"credits": 32.185,
"requests": 314,
"prompt_tokens": 22191,
"completion_tokens": 13744
}
]
}
}
```
```json 400 theme={null}
{
"success": false,
"error": {
"code": "range_too_large",
"message": "Time range must not exceed 31 days.",
"type": "usage_query_error"
}
}
```
## 認証
モデル呼び出しと同じ API Key を Bearer Token として使用します。[API Key 管理ページ](https://apimart.ai/keys)でキーを取得してください。
```
Authorization: Bearer YOUR_API_KEY
```
残高が 0 でも照会できます。残高は検証しませんが、API Key の状態、有効期限、IP 許可リスト、アカウント状態は検証します。
## エンドポイント
```text theme={null}
GET /v1/usage
GET /usage
```
両エンドポイントは同じ機能を提供し、CORS に対応します。API Key を適切に保管し、公開フロントエンドコードに露出させないでください。
## リクエストパラメータ
すべてのパラメータは URL のクエリで渡します。
開始時刻を含みます。秒単位の Unix タイムスタンプ、またはタイムゾーン付き RFC3339 文字列（例：`2026-09-01T00:00:00+08:00`）を使用できます。
省略時は `end` の 24 時間前。タイムスタンプはミリ秒ではなく秒単位です。
終了時刻を含みません。`start` と同じ形式を使用し、省略時は現在時刻です。
`start` より後である必要があり、`end - start` は 31 日以内です。
モデル名。省略時は全モデルを対象とします。複数モデルは半角コンマで区切り、最大 `50` 個です。
大文字・小文字を区別しない完全一致。ワイルドカードは非対応です。
例：`gpt-5.6-luna,sora-2`
集計方法：
* `none`：合計のみ返し、`items` は空配列
* `model`：モデル別に集計
* `date`：暦日別に集計
* `model,date`：モデルと暦日の組み合わせで集計
IANA タイムゾーン名。既定値は `Asia/Shanghai`。
`group_by` が `date` を含む場合の暦日境界のみに影響し、照会の開始・終了時刻は変更しません。RFC3339 時刻は文字列自身のタイムゾーンで解析されます。
統計対象：
* `key`：現在の API Key のみ（既定）
* `account`：現在の API Key が属するアカウントの全 API Key を合算
照会期間は `[start, end)`（開始を含み、終了を含まない）です。前の照会の `end` と次の照会の `start` を同じ時刻にすると、境界を重複計算しません。
URL を手動で組み立てる場合、RFC3339 の `+` は `%2B` にエンコードしてください。例の cURL `--data-urlencode`、Python `params`、JavaScript `URLSearchParams` は自動で処理します。
## リクエスト例
### 現在の API Key の直近 24 時間の消費合計
クエリパラメータを省略すると、既定の期間・対象・集計方法を使用します。
```bash theme={null}
curl 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer '
```
### アカウント全体における指定モデルの日別消費
北京時間の 2026 年 9 月 11 日から 9 月 18 日まで（9 月 18 日を含まない）の消費を照会します。
```bash theme={null}
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer ' \
--data-urlencode 'start=1789056000' \
--data-urlencode 'end=1789660800' \
--data-urlencode 'model=gpt-5.6-luna' \
--data-urlencode 'group_by=date' \
--data-urlencode 'scope=account' \
--data-urlencode 'tz=Asia/Shanghai'
```
### モデルと暦日の組み合わせで集計
```bash theme={null}
curl --get 'https://api.apimart.ai/v1/usage' \
--header 'Authorization: Bearer ' \
--data-urlencode 'start=2026-09-01T00:00:00+08:00' \
--data-urlencode 'end=2026-09-08T00:00:00+08:00' \
--data-urlencode 'model=gpt-5.6-luna,sora-2' \
--data-urlencode 'group_by=model,date' \
--data-urlencode 'tz=Asia/Shanghai'
```
この集計方法では、各 `items` 要素に `model` と `date` の両方が含まれます。
## レスポンスフィールド
照会の成否。成功時は `true`、用量照会エラー時は `false`。
成功時に照会範囲、合計、集計明細を返します。
統計対象：`key` または `account`。
実際の開始時刻。秒単位の Unix タイムスタンプ、開始を含む。
実際の終了時刻。秒単位の Unix タイムスタンプ、終了を含まない。
暦日別集計に使用したタイムゾーン。
集計方法：`none`、`model`、`date`、`model,date`。
照会範囲の合計。統計フィールドは下表を参照。
集計明細。`amount_usd` の降順で並び、`group_by=none` では空配列です。各要素は下表の統計フィールドを含みます。
* `group_by` に `model` が含まれる場合、要素に `model` を含む
* `group_by` に `date` が含まれる場合、要素に `date` を含む。形式は `YYYY-MM-DD`、暦日は `tz` で区切る
`data.total` と `data.items[]` は次の統計フィールドを共有します。
| フィールド | 型 | 説明 |
| ------------------- | ------- | ----------------------------------------- |
| `amount_usd` | number | 米ドル金額、小数点以下 6 桁に丸める |
| `credits` | number | サイト内クレジット。`amount_usd × 10`、公式サイトの表示単位と同じ |
| `requests` | integer | 課金が成功した呼び出し回数 |
| `prompt_tokens` | integer | 入力トークン数。呼び出し単位・秒単位で課金する画像・動画モデルは通常 0 |
| `completion_tokens` | integer | 出力トークン数。呼び出し単位・秒単位で課金する画像・動画モデルは通常 0 |
用量照会エラー時に返し、`code`、`message`、`type` を含みます。`type` は `usage_query_error`。401 / 403 の認証エラーは認証レイヤーから返されます。
## レート制限とキャッシュ
* API Key ごとに毎分最大 `60` 回。グローバル API レート制限も適用
* 同一パラメータの結果は `60` 秒キャッシュ。レスポンスヘッダー `X-Usage-Cache` は `hit` または `miss`
* 消費記録は通常 1 秒以内に照会可能ですが、直近 1 分のデータは不完全な場合があり、キャッシュ遅延もあります
* 照会間隔は 1 分以上を推奨。リアルタイム課金通知としては使用しないでください
## 統計の基準
* 課金が成功した呼び出し記録を使用し、公式サイトのダッシュボードと同じデータです
* 失敗呼び出し・失敗後に返金されたタスクは除外され、手動相殺は不要。画像バッチが部分成功した場合は実際に提供した枚数で課金
* 課金の計上時刻で消費を帰属。非同期画像・動画タスクは送信時ではなく完了時に計上し、日付をまたぐタスクは完了日に属します
* 削除後に再作成した API Key は新しい Key。新 Key の `scope=key` 照会に旧 Key の履歴は含まれません
* 手動の残高調整は呼び出し消費ではなく、統計対象外
* 2026 年 4 月 27 日より後のデータを照会可能
## エラー処理
| HTTP ステータス | `error.code` | 説明 |
| ---------- | ------------------------------- | ----------------------------------------- |
| 400 | `invalid_start` / `invalid_end` | 開始・終了時刻の形式が無効 |
| 400 | `invalid_range` | `end` が `start` より後ではない |
| 400 | `range_too_large` | 31 日超。期間を複数の照会に分割してください |
| 400 | `invalid_tz` | 不明な IANA タイムゾーン |
| 400 | `invalid_group_by` | 集計方法が無効 |
| 400 | `invalid_scope` | 統計対象が無効 |
| 400 | `too_many_models` | モデルが 50 個超 |
| 401 / 403 | — | API Key が無効・期限切れ、IP が許可されていない、またはアカウントが無効 |
| 429 | — | Key ごとの毎分 60 回超、またはグローバル API レート制限 |
| 503 | `usage_unavailable` | 用量データが一時的に利用不可。後で再試行 |
`503 usage_unavailable` では金額は返りません。照会できないことを意味し、消費が 0 という意味ではありません。失敗レスポンスをゼロ金額に変換したり、過去の成功結果を上書きしないでください。
## 他のエンドポイントとの違い
| エンドポイント | 機能 |
| --------------------------------- | ---------------------------------- |
| `GET /v1/dashboard/billing/usage` | 累計消費のみ返却。モデル・期間での絞り込み不可 |
| `POST /v1/logs/export` | 呼び出し明細を非同期で出力（CSV / XLSX）。集計は自分で行う |
| `GET /v1/usage` | 期間・モデルで照会し、消費合計と集計明細を直接返却 |
残りの利用枠は [トークン残高の照会](/ja/api-reference/account/token-balance) または [ユーザー残高の照会](/ja/api-reference/account/user-balance) を使用してください。