# Batches API リファレンス — 開始、エクスポート、削除

> アップロードしたドキュメントのバッチ抽出を開始し、バッチの一覧表示とフィルタリング、集計ステータスのポーリング、再構成されたJSON結果の取得、Excel/Wordへのエクスポート、ImageToTable.ai v1 APIでのバッチ削除を行います。

**バッチ**とは、1つ以上の[ドキュメント](/developers/reference/documents)をグループ化し、まとめて処理、ステータス確認、結果取得を行うための名前付きグループです。バッチを明示的に作成する必要はありません。ドキュメントを`batch_name`を指定してアップロードすると（[ドキュメントのアップロード](/developers/reference/documents#upload-a-document)を参照）、初回アップロード時に暗黙的に作成されます。

## バッチの処理を開始する

現在バッチ内にあるすべての対象ドキュメント（`processing`または`succeeded`状態でないもの）の抽出を開始します。このエンドポイントで実際にクレジットが消費されます（キューに入ったドキュメント1件につき1クレジット）。

`POST /api/v1/batches/{batch_name}/process`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| batch_name | path | string | 処理するバッチ名。 |
| template_id | body (JSON) | integer, 省略可 | 適用する保存済みテンプレート。 fields と両方指定された場合はこちらが優先されます。 |
| fields | body (JSON) | array, 省略可 | この実行のみに使用するアドホックなフィールドリスト。 [{"name": "...", "format_requirement": "..."}] またはフィールド名の文字列配列。 template_id が指定された場合は無視されます。両方を省略すると、モデルが自動的に列を推論します。 |
| quality | body (JSON) | string, 省略可 | "fast" または "high" 。省略すると、アカウントの thinking_type 設定が適用されます。 アカウント設定とAPIの動作 を参照してください。 |
| webhook_url | body (JSON) | string, 省略可 | このバッチの完了コールバックを同じ呼び出しで登録（または更新）します。 バッチWebhookの登録 と同等です。 http:// または https:// である必要があります。 |
| Idempotency-Key | header, 省略可 | string | 強く推奨 — このエンドポイントはクレジットを消費します。 冪等性 を参照してください。 |

`quality` は、API が呼び出しごとに上書きできる唯一のアカウント設定です。その他のアカウントレベルの設定（bbox 自動注釈、保持ポリシー）はアカウントから読み取られ、リクエストごとに上書きすることはできません。詳細は [アカウント設定とAPIの動作](/developers/guides/account-settings) をご覧ください。この中では、`auto_annotate_bbox` が、そのエンドポイントを呼び出していなくても、この呼び出しで bbox 注釈の料金が発生する理由についても説明しています。

**レスポンスの `webhook_registered` は、この特定の呼び出しのみを反映します** — このリクエストに `webhook_url` が含まれていた場合にのみ `true` となり、バッチに Webhook が設定されているかどうかは関係ありません。以前に [バッチWebhookの登録](/developers/reference/webhooks) で Webhook が設定され（ここでは繰り返されていない）、完了時にコールバックが正しく実行されるバッチでも、このフィールドはその呼び出しでは `false` を返します。既存の `BatchWebhook` があるかどうかを確認することはありません。ここで `false` が返されても、「このバッチでは Webhook が実行されない」と判断しないでください。

すでに処理して通知を受け取ったバッチに対して、さらにドキュメントをアップロードした後に、このエンドポイントを再度呼び出すと、そのバッチの Webhook がすでに実行されていた場合、自動的に再設定され、新しい波の完了時にも通知が行われます。これを実現するために追加の呼び出しは必要ありません。正確なセマンティクス（2つの波が重なった場合の動作を含む）については、[Webhookガイド](/developers/guides/webhooks#reprocessing-a-batch) の「バッチの再処理」セクションを参照してください。

### 発生する可能性のあるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors) を参照してください。
- `batch_not_found` — お客様のアカウントに、この `batch_name` のドキュメントが存在しません。
- `invalid_parameter` — `quality`/`webhook_url`/`template_id` の値が不正であるか、バッチ内に現在処理可能なドキュメントがありません（すべて完了済み/処理中、またはバッチが空です）。
- `template_not_found`
- `insufficient_credits` — キューに入れようとしているドキュメントをカバーするのに十分なクレジットがありません。

## バッチ一覧

バッチのページネーション対応・フィルタ可能な要約リストを返します。API利用者向けの「Files Filter」相当の機能です。ここでは要約（`document_count`、集計`status`）のみを返します。特定バッチの完全なドキュメント単位データを取得するには[バッチ結果の取得](#get-batch-results)を使用してください。

`GET /api/v1/batches`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| source | query, オプション | string | direct 、 collect 、 email_inbox 、 api （メインWebアプリの direct とは別に POST /documents でアップロード）、または share （ collect と email_inbox の両方をカバーするエイリアス）のいずれか。省略すると全ソースが対象になります。 |
| q | query, オプション | string | バッチ内のファイル名に対する大文字小文字を区別しない部分一致検索。 |
| date_from | query, オプション | string ( YYYY-MM-DD ) | アップロード時刻の下限（指定日を含む）。 |
| date_to | query, オプション | string ( YYYY-MM-DD ) | アップロード時刻の上限（指定日の終了時を含む）。 |
| status | query, オプション | string | フィルタする公開ステータス（ queued,processing,succeeded,failed,canceled ）のカンマ区切りリスト。 |
| template_id | query, オプション | integer | このテンプレートを使用したバッチのみ。 |
| mode | query, オプション | string | 現時点で受け付け可能な値は "table" のみです（v1が現在サポートする唯一のモード）。将来の抽出モード用に予約されています。 |
| limit | query, オプション | integer | 1～100。デフォルトは20。 |
| page_token | query, オプション | string | 前回のレスポンスの next_page_token から取得する不透明なカーソル。詳細は ページネーション を参照してください。 |

### 発生しうるエラー

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

## バッチステータスの取得

1つのバッチに対する軽量な集計ステータスです。公開ステータスごとの件数と`all_done`フラグを返します。完全な結果ペイロードがまだ不要な、安価なポーリングループに便利です。

`GET /api/v1/batches/{batch_name}`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| batch_name | path | string | 確認するバッチを指定します。 |

### 発生しうるエラー

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

## バッチ結果の取得

抽出データを取得する主要な方法です。バッチ内のすべてのドキュメントが、再構成された`line_items`（抽出された行ごとに`{field_name: value}`オブジェクトの配列）とともに返されます。フィールドレベルの値は、デフォルトでは単なるスカラー値（文字列、数値など）です。

`GET /api/v1/batches/{batch_name}/results`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| batch_name | path | string | 結果を取得するバッチを指定します。 |
| include | query, optional | string | "bbox" — 設定すると、すべてのフィールド値が単なるスカラー値ではなく {"value": ..., "bbox": {...}|null} になり、各ドキュメントに bbox_status フィールドが追加されます。以下の注意事項をご参照ください。これは新しいbboxジョブを 決して トリガーせず、すでに計算済みのもののみを返します。 |

`?include=bbox`は、バックフィルされた結果のみを読み取ります。つまり、[bboxアノテーションのトリガー](/developers/reference/documents#trigger-bbox-annotation)を代わりに実行することはありません。ドキュメントに対してbboxが一度もトリガーされていない場合（手動、またはアカウントの`auto_annotate_bbox`設定による場合）、そのドキュメントのフィールドは単に`"bbox": null`として返されます。

**位置情報のみのフィールドは、これらとは異なる第3の形状です。**一部のテンプレートフィールドは、テキストを書き写すのではなく、何かを特定するようモデルに指示します（例：「ポートレート写真の位置を特定する」）。これらのフィールドでは、値全体*が*位置情報です。そのため、スカラー値や上記の`{"value","bbox"}`ペアの代わりに、`{"type": "image_region", "bbox": {...}, "image_url": "..."}`が返されます。**これは`?include=bbox`が設定されているかどうかに関係なく**行われます。ここでのボックスはオプションのメタデータではなく、フィールドの唯一の内容です。`image_url`は、すぐに取得可能な切り抜きJPEG画像を指します（[ドキュメント画像の取得](/developers/reference/documents#get-a-document-image)を参照）。そのため、4つの数値から元の画像を自分で切り抜く必要はありません。

すべての `bbox` オブジェクトは、形状に関わらず `"unit": "normalized"` を使用します。座標はページの幅・高さに対する0から1の浮動小数点数であり、ピクセルや0～1000のスケールではありません。精度に関する注意事項については、[バウンディングボックス](/developers/guides/bbox) ガイドを参照してください。これらの座標はモデルから直接取得され、ピクセルレベルの検証は行われていません。そのため、密度の高い文書や複雑な文書では「正確」ではなく「近い」値として扱ってください。

### 考えられるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラーハンドリング](/developers/guides/errors) を参照してください。
- `batch_not_found`

## バッチのエクスポート

便利なダウンロード機能です。上記の `results` は、このAPIが基盤とする正規の構造化フォーマットです。このエンドポイントは、自分で整形コードを書かずに同じデータをスプレッドシートに取り込むために存在します。xlsxのみ対応しています。v1はテーブル（抽出）モードのみをサポートし、メインアプリでのWord（docx）エクスポートは、専らpage_wordモードのネイティブ出力（まったく異なるプロンプトと結果形状）であり、v1では公開されていません。ここでは「Word文書としてのテーブルデータ」オプションはありません。

`GET /api/v1/batches/{batch_name}/export`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| batch_name | パス | 文字列 | エクスポートするバッチ。 |
| format | クエリ（オプション） | 文字列 | xlsx （デフォルト）のみ受け付けます。 |

レスポンスはファイルダウンロード（`Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`）であり、JSONではありません。このエンドポイントにはレスポンスJSONの例はありません。

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラー処理](/developers/guides/errors)をご覧ください。
- `batch_not_found`
- `invalid_parameter` (`param: "format"`) — `xlsx`以外の値が指定された場合。

## バッチを削除する

バッチ内のすべてのドキュメントを完全に削除します。削除前に、`queued`状態のドキュメントは返金されます。また、バッチのWebhook登録（存在する場合）と、そのドキュメントに関連するbboxアノテーションジョブも削除されます。

`DELETE /api/v1/batches/{batch_name}`

### パラメータ

| 名前 | 場所 | 型 | 説明 |
| --- | --- | --- | --- |
| batch_name | path | string | 削除するバッチを指定します。 |

### 発生しうるエラー

- `missing_api_key` / `invalid_api_key` / `plan_required` — [エラー処理](/developers/guides/errors)をご覧ください。
- `batch_not_found` — 他のリソースとは異なり、所有していない（または存在しない）`batch_name`を削除しようとすると、ここではエラーを返さずに無視するのではなく、404エラーが発生します。

## Code Examples

### バッチ処理を開始

POST /api/v1/batches/{batch_name}/process

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/july-invoices/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
        "fields": [
          {"name": "invoice_number"},
          {"name": "invoice_date", "format_requirement": "YYYY-MM-DD"},
          {"name": "total_amount"}
        ],
        "quality": "high",
        "webhook_url": "https://example.com/webhooks/imagetotable"
      }'
```

**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/july-invoices/process",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "fields": [
            {"name": "invoice_number"},
            {"name": "invoice_date", "format_requirement": "YYYY-MM-DD"},
            {"name": "total_amount"},
        ],
        "quality": "high",
        "webhook_url": "https://example.com/webhooks/imagetotable",
    },
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      { name: "invoice_number" },
      { name: "invoice_date", format_requirement: "YYYY-MM-DD" },
      { name: "total_amount" },
    ],
    quality: "high",
    webhook_url: "https://example.com/webhooks/imagetotable",
  }),
});
console.log(await response.json());
```

### レスポンス

```json
{
  "batch_name": "july-invoices",
  "queued": 3,
  "quality": "high",
  "webhook_registered": true
}
```

### 処理開始 — 保存済みテンプレートを使用

POST /api/v1/batches/{batch_name}/process

抽出内容を指定するもう1つの方法です。 `template_id` と `fields` の両方を送信した場合、`template_id` が優先されます。 毎回アドホックに宣言するのではなく、同じ列リストを複数回の実行で再利用する場合には、こちらがより一般的な選択肢です。

**cURL**

```bash
curl -X POST https://imagetotable.ai/api/v1/batches/july-invoices/process \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template_id": 42}'
```

**Python**

```python
import os
import uuid
import requests

response = requests.post(
    "https://imagetotable.ai/api/v1/batches/july-invoices/process",
    headers={
        "Authorization": f"Bearer {os.environ['API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"template_id": 42},
)
print(response.json())
```

**Javascript**

```javascript
const response = await fetch("https://imagetotable.ai/api/v1/batches/july-invoices/process", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ template_id: 42 }),
});
console.log(await response.json());
```

### レスポンス

```json
{
  "batch_name": "july-invoices",
  "queued": 3,
  "quality": "fast",
  "webhook_registered": false
}
```

ここでの `quality` が `"fast"` なのは、 リクエストで省略されたためアカウントの `thinking_type` 設定にフォールバックしたからであり、 テンプレートを使用したからではありません。`template_id`/`fields` と `quality` は独立したパラメータです。

### バッチ一覧

GET /api/v1/batches

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/batches?status=succeeded&limit=20" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/batches");
url.searchParams.set("status", "succeeded");
url.searchParams.set("limit", "20");

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

### レスポンス

```json
{
  "data": [
    {
      "batch_name": "july-invoices",
      "status": "succeeded",
      "document_count": 3,
      "created_at": "2026-07-16T09:12:03+00:00"
    }
  ],
  "has_more": false,
  "next_page_token": null
}
```

### バッチステータスの取得

GET /api/v1/batches/{batch_name}

**cURL**

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

**Python**

```python
import os
import requests

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

**Javascript**

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

### レスポンス

```json
{
  "batch_name": "july-invoices",
  "document_count": 3,
  "status_counts": {
    "queued": 0,
    "processing": 0,
    "succeeded": 3,
    "failed": 0,
    "canceled": 0
  },
  "all_done": true,
  "created_at": "2026-07-16T09:12:03+00:00"
}
```

### バッチ結果の取得

GET /api/v1/batches/{batch_name}/results

**cURL**

```bash
curl https://imagetotable.ai/api/v1/batches/july-invoices/results \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

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

### レスポンス — デフォルト（includeなし）

```json
{
  "batch_name": "july-invoices",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03+00:00",
  "started_at": "2026-07-16T09:12:05+00:00",
  "completed_at": "2026-07-16T09:12:14+00:00",
  "documents": [
    {
      "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
      "filename": "invoice_042.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03+00:00",
      "started_at": "2026-07-16T09:12:05+00:00",
      "completed_at": "2026-07-16T09:12:14+00:00",
      "line_items": [
        {
          "invoice_number": "INV-1042",
          "invoice_date": "2026-07-01",
          "total_amount": "1,204.50"
        }
      ]
    }
  ]
}
```

### バッチ結果の取得 — bbox付き

GET /api/v1/batches/{batch_name}/results?include=bbox

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/batches/july-invoices/results?include=bbox" \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/july-invoices/results",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"include": "bbox"},
)
print(response.json())
```

**Javascript**

```javascript
const url = new URL("https://imagetotable.ai/api/v1/batches/july-invoices/results");
url.searchParams.set("include", "bbox");

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

### レスポンス — `?include=bbox`

```json
{
  "batch_name": "july-invoices",
  "status": "succeeded",
  "created_at": "2026-07-16T09:12:03+00:00",
  "started_at": "2026-07-16T09:12:05+00:00",
  "completed_at": "2026-07-16T09:12:14+00:00",
  "documents": [
    {
      "document_id": "8f14e45f-ceea-467e-9de1-a3e9c93a9c95",
      "filename": "invoice_042.jpg",
      "status": "succeeded",
      "created_at": "2026-07-16T09:12:03+00:00",
      "started_at": "2026-07-16T09:12:05+00:00",
      "completed_at": "2026-07-16T09:12:14+00:00",
      "bbox_status": "succeeded",
      "line_items": [
        {
          "invoice_number": {
            "value": "INV-1042",
            "bbox": {"x1": 0.121, "y1": 0.084, "x2": 0.418, "y2": 0.112, "unit": "normalized"}
          },
          "total_amount": {
            "value": "1,204.50",
            "bbox": null
          },
          "portrait_photo": {
            "type": "image_region",
            "bbox": {"x1": 0.740, "y1": 0.060, "x2": 0.920, "y2": 0.260, "unit": "normalized"},
            "image_url": "https://imagetotable.ai/api/v1/documents/8f14e45f-ceea-467e-9de1-a3e9c93a9c95/image?crop=0.7241%2C0.0426%2C0.9359%2C0.2774"
          }
        }
      ]
    }
  ]
}
```

### バッチのエクスポート

GET /api/v1/batches/{batch_name}/export

**cURL**

```bash
curl "https://imagetotable.ai/api/v1/batches/july-invoices/export?format=xlsx" \
  -H "Authorization: Bearer $API_KEY" \
  -o july-invoices.xlsx
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://imagetotable.ai/api/v1/batches/july-invoices/export",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
    params={"format": "xlsx"},
)
with open("july-invoices.xlsx", "wb") as f:
    f.write(response.content)
```

**Javascript**

```javascript
import { writeFile } from "node:fs/promises";

const url = new URL("https://imagetotable.ai/api/v1/batches/july-invoices/export");
url.searchParams.set("format", "xlsx");

const response = await fetch(url, {
  headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
});
await writeFile("july-invoices.xlsx", Buffer.from(await response.arrayBuffer()));
```

### バッチの削除

DELETE /api/v1/batches/{batch_name}

**cURL**

```bash
curl -X DELETE https://imagetotable.ai/api/v1/batches/july-invoices \
  -H "Authorization: Bearer $API_KEY"
```

**Python**

```python
import os
import requests

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

**Javascript**

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

### レスポンス

```json
{
  "batch_name": "july-invoices",
  "deleted": 3,
  "canceled": 1
}
```

---

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