> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# バッチを取得

> ID を指定してバッチを取得します。

`GET /api/v1/forward/batches/{batch_id}`

バッチオブジェクトの全体を返します。現在のタスクカウンタと、終端状態到達後は出力ファイル ID も含まれます。

## Headers

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Path parameters

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `batch_id` | string | Yes      | バッチ ID。     |

## Example request

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/batches/batch_completed001' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "id": "batch_completed001",
  "object": "batch",
  "status": "completed",
  "input_file_id": "file_input001",
  "output_file_id": "file_output001",
  "completion_window": "24h",
  "created_at": "2026-07-07T07:25:01Z",
  "expires_at": "2026-07-08T07:25:01Z",
  "request_counts": {
    "total": 30,
    "pending": 0,
    "running": 0,
    "completed": 30,
    "failed": 0,
    "cancelled": 0,
    "expired": 0
  },
  "usage": null
}
```

## Response fields

| Field               | Type        | Description                         |
| ------------------- | ----------- | ----------------------------------- |
| `id`                | string      | バッチ ID。プレフィックスは `batch_`。           |
| `object`            | string      | 常に `batch`。                         |
| `status`            | string      | バッチステータス。                           |
| `input_file_id`     | string      | 入力 JSONL ファイル ID。                   |
| `output_file_id`    | string      | 成功行の結果ファイル ID。生成前は省略されます。           |
| `error_file_id`     | string      | 失敗行の結果ファイル ID。失敗行がない場合は省略されます。      |
| `completion_window` | string      | 完了ウィンドウ。                            |
| `created_at`        | string      | 作成時刻。RFC 3339。                      |
| `expires_at`        | string      | 有効期限。                               |
| `request_counts`    | object      | タスクカウンタの集計値。                        |
| `usage`             | object/null | 予約フィールド。v1 では常に `null`。             |
| `metadata`          | object      | 呼び出し元のメタデータ。                        |
| `error_message`     | string      | バッチ単位のエラーメッセージ。`failed` の場合のみ返されます。 |

## Error codes

| HTTP | Type                   | Code                      | Trigger                  |
| ---- | ---------------------- | ------------------------- | ------------------------ |
| 404  | `not_found_error`      | `batch_not_found`         | バッチが存在しない、または他ユーザーのものです。 |
| 401  | `authentication_error` | `authentication_required` | PAT が無効または期限切れです。        |

## Notes

* 他ユーザーのバッチにアクセスすると `404 batch_not_found` が返ります。
* クライアントはこの API をポーリングして、バッチが終端状態（`completed` / `failed` / `cancelled` / `expired`）に達したかどうかを確認してください。

## Related

<CardGroup cols={2}>
  <Card title="バッチの一覧取得" icon="list" href="/ja/cloud-agents/api/forward/batches/list" />

  <Card title="出力ファイルの取得" icon="download" href="/ja/cloud-agents/api/forward/batches/get-output" />
</CardGroup>