# アカウントAPIリファレンス — プラン、クレジット、使用量

> 現在の有効プラン、ロール、利用可能クレジット、SDKが尊重すべきスロットリング制限、およびImageToTable.ai v1 APIのポイント消費履歴を確認できます。

APIキーが属するアカウント用の2つの読み取り専用エンドポイント：プランと利用可能クレジットのスナップショット（SDKがセルフスロットリングに必要な2つの数値を含む）、およびセルフサービスでの調整のためのクレジット消費のページネーション付き台帳です。

## アカウントの取得

アカウントの**有効**プランとクレジットを返します。アカウントがチームのメンバーである場合、これは個人のメンバーシッププランではなく、チームオーナーのプラン/クレジットプールを反映します。

`GET /api/v1/account`

### パラメータ

なし — アカウントは`Authorization`ヘッダーのAPIキーによって完全に決定されます。

`max_batch_size`と`upload_concurrency`は、クライアントSDKが`invalid_parameter`/`rate_limit_exceeded`エラーに最初に当たってからこれらの制限を発見するのではなく、自身のアップロードループをセルフスロットリングできるように提供されています。

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — 詳細は[エラーハンドリング](/developers/guides/errors)をご覧ください。

## アカウント使用量の取得

アカウント上のクレジットに影響するすべてのイベント（抽出による消費、バウンディングボックス注釈による消費、返金）を、新しい順にページネーションで表示する台帳です。「この処理にクレジットがいくらかかったか」を確認するためのもので、UI駆動を目的としていません（`/profile/usage_history`の整形済み表示文字列と比較してください。このエンドポイントはそのような文字列を返さず、代わりに構造化された符号付き`amount`値を返します）。

`GET /api/v1/account/usage`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| limit | クエリ、オプション | 整数 | 1～200。デフォルトは50。 |
| batch_name | クエリ、オプション | 文字列 | 台帳を特定のバッチのエントリに制限します。「バッチXのクレジット消費量はいくらか」を確認する場合に使用します。 |
| page_token | クエリ、オプション | 文字列 | 前回のレスポンスの next_page_token から受け取る不透明なカーソルです。このエンドポイントは 新しい順 にページネーションします（他のv1リストエンドポイントは古い順です）。トークンは不透明で、同じ方法でラウンドトリップしますが、内部の順序のみが異なります。詳細は ページネーション をご覧ください。 |

`amount`は符号付きです。負の値は消費（抽出/バウンディングボックス注釈による消費）、正の値はクレジットの戻り（返金/キャンセル返金）を表します。そのため、1ページの`amount`値を合計すると、そのページの正味の変化量が得られます。`document_id`は[ドキュメント](/developers/reference/documents)の`document_id`と同じID空間です（内部台帳では`task_id`と呼ばれますが、このエンドポイントではv1の他の部分との一貫性のために名前を変更しています）。

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — 詳細は[エラーハンドリング](/developers/guides/errors)をご覧ください。
- `invalid_parameter` — `limit`または`page_token`が不正です。

## Code Examples

### アカウント情報の取得

GET /api/v1/account

**cURL**

```bash
curl https://imagetotable.ai/api/v1/account \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/account",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/account", {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### レスポンス

```json
{
  "plan": "Pro",
  "role": "User",
  "available_credits": 842,
  "max_batch_size": 200,
  "upload_concurrency": 4
}
```

### アカウント使用状況を取得

GET /api/v1/account/usage

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/account/usage?batch_name=july-invoices&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/account/usage",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"batch_name": "july-invoices", "limit": 50},
)
print(response.json())
```

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/account/usage");
url.searchParams.set("batch_name", "july-invoices");
url.searchParams.set("limit", "50");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
console.log(await response.json());
```

### レスポンス

```json
{
  "data": [
    {
      "id": 88213,
      "action": "deduction",
      "batch_name": "july-invoices",
      "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
      "point_type": "personal",
      "amount": -1,
      "consumer_id": 501,
      "created_at": "2026-07-16T09:12:05+00:00"
    },
    {
      "id": 88190,
      "action": "refund",
      "batch_name": "june-receipts",
      "document_id": "1b2c3d4e-5f60-7182-93a4-b5c6d7e8f901",
      "point_type": "personal",
      "amount": 1,
      "consumer_id": 501,
      "created_at": "2026-07-15T14:02:11+00:00"
    }
  ],
  "has_more": true,
  "next_page_token": "eyJpZCI6ODgxOTB9"
}
```

---

Source: https://imagetotable.ai/ja/developers/reference/account