# Batches API Reference — Start, Export & Delete

> 업로드된 문서 배치에 대한 추출을 시작하고, 배치를 나열 및 필터링하며, 전체 상태를 확인하고, 재구성된 JSON 결과를 가져오고, Excel/Word로 내보내고, ImageToTable.ai v1 API의 배치를 삭제합니다.

**배치**는 함께 처리하고, 상태를 확인하며, 결과를 가져오는 하나 이상의 [문서](/developers/reference/documents)로 구성된 명명된 그룹입니다. 배치를 명시적으로 생성할 필요는 없습니다. 해당 `batch_name`으로 문서를 처음 업로드할 때 암시적으로 생성됩니다([문서 업로드](/developers/reference/documents#upload-a-document) 참조).

## 배치 처리 시작

현재 배치에 있는 모든 적격 문서에 대한 추출을 시작합니다. 이 엔드포인트는 실제로 크레딧을 사용하며, 대기열에 추가된 문서당 1크레딧이 차감됩니다.

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

### 매개변수

| 이름 | 위치 | 유형 | 설명 |
| --- | --- | --- | --- |
| batch_name | path | string | 처리할 배치입니다. |
| template_id | body (JSON) | integer, optional | 적용할 저장된 템플릿입니다. fields 와 함께 제공된 경우 template_id 가 우선합니다. |
| fields | body (JSON) | array, optional | 이번 실행에만 사용할 임시 필드 목록입니다. — [{"name": "...", "format_requirement": "..."}] 또는 일반 이름 문자열 배열입니다. template_id 가 제공되면 무시됩니다. 둘 다 생략하면 모델이 자체적으로 열을 추론합니다. |
| quality | body (JSON) | string, optional | "fast" 또는 "high" 입니다. 생략하면 계정의 thinking_type 설정이 사용됩니다. — 계정 설정 및 API 동작 을 참조하세요. |
| webhook_url | body (JSON) | string, optional | 동일한 호출에서 이 배치의 완료 콜백을 등록합니다. — 배치 Webhook 등록 을 호출하는 것과 동일합니다. http:// 또는 https:// 여야 합니다. |
| Idempotency-Key | header, optional | string | 강력히 권장됩니다. 이 엔드포인트는 크레딧을 차감합니다. 멱등성 을 참조하세요. |

`quality`는 API가 호출별로 재정의할 수 있게 허용하는 유일한 계정 설정입니다. 다른 모든 계정 수준 기본 설정은 계정에서 읽어오며 요청별로 재정의할 수 없습니다. 전체 내용은 [계정 설정 및 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이 이미 실행된 경우 자동으로 재설정되어 새 문서 배치의 완료도 알림을 받게 됩니다. 이를 위해 추가 호출이 필요하지 않습니다. 정확한 의미는 [Webhooks 가이드](/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" 기능입니다. 요약 정보만 반환하며, 특정 배치의 전체 문서별 데이터는 [배치 결과 조회](#get-batch-results)를 사용하세요.

`GET /api/v1/batches`

### 파라미터

| 이름 | 위치 | 타입 | 설명 |
| --- | --- | --- | --- |
| source | query, 선택 | string | direct , collect , email_inbox , api , 또는 share 중 하나. 생략 시 모든 소스. |
| 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" 입니다. 향후 추출 모드를 위해 예약됨. |
| 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`이 잘못되었습니다.

## 배치 상태 가져오기

하나의 배치에 대한 간단한 집계 상태 — 공개 상태별 개수와 `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`와 함께 반환됩니다. `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가 트리거된 적이 없는 경우, 해당 문서의 필드는 단순히 `"bbox": null`로 반환됩니다.

**순수 위치 필드는 세 번째 별도 형태입니다.** 일부 템플릿 필드는 텍스트를 추출하는 대신 무언가를 찾도록 모델에 요청합니다. 해당 필드의 경우 전체 값이 *위치*입니다. 따라서 위의 스칼라나 `{"value","bbox"}` 쌍 대신 `{"type": "image_region", "bbox": {...}, "image_url": "..."}`을 받게 됩니다. `?include=bbox` 설정 여부와 **관계없이** — 여기서 박스는 선택적 메타데이터가 아니라 필드의 유일한 내용입니다. `image_url`은 바로 가져올 수 있는 잘린 JPEG을 가리킵니다([문서 이미지 가져오기](/developers/reference/documents#get-a-document-image) 참조). 따라서 네 개의 숫자로 원본을 직접 자를 필요가 없습니다.

모든 `bbox` 객체는 `"unit": "normalized"`를 사용합니다. 좌표는 페이지의 너비/높이를 기준으로 0에서 1 사이의 부동소수점이며, 픽셀이나 0–1000 스케일이 아닙니다. 정확도에 대한 주의사항은 [Bounding Boxes](/developers/guides/bbox) 가이드를 참조하세요. 이 좌표들은 픽셀 수준의 검증 과정 없이 모델에서 직접 가져온 것이므로, 복잡하거나 빽빽한 문서에서는 정확하다기보다 "근사치"로 간주해야 합니다.

### 가능한 오류

- `missing_api_key` / `invalid_api_key` / `plan_required` — [Error Handling](/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 | path | string | 내보낼 배치입니다. |
| format | query, 선택 사항 | string | xlsx 만 허용됩니다. |

응답은 JSON이 아닌 파일 다운로드(`Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`)입니다. 이 엔드포인트에 대한 응답 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

추출할 내용을 지정하는 두 가지 방법 중 하나입니다. `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());
```

### 응답 — 기본값

```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/ko/developers/reference/batches