> ## 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. # バッチを作成 > JSONL 入力ファイルから非同期のバッチジョブを作成します。 `POST /api/v1/forward/batches` Forward が入力ファイルと JSONL 行フォーマットを検証したうえで、オフピーク時間帯に自動的にスケジュールされます。完了後は `output.jsonl` と `error.jsonl` がダウンロード用に生成されます。 ## Headers | Header | Required | Description | | ----------------- | -------- | ----------------------- | | `Authorization` | Yes | `Bearer ` | | `Content-Type` | Yes | `application/json` | | `Idempotency-Key` | No | 安全でないリクエスト向けの任意のべき等性キー。 | ## 事前準備: 入力ファイルのアップロード バッチを作成するには、まず JSONL 形式の入力ファイルを用意し、CAS Files API 経由でアップロードして `file_id` を取得します。 **JSONL フォーマット**: 1 行につき 1 個の JSON オブジェクトが 1 タスクを表します。 ```jsonl theme={null} {"custom_id": "task-001", "template_id": "tmpl_example001", "identity_id": "idn_example001", "body": {"input": "こんにちは"}} {"custom_id": "task-002", "template_id": "tmpl_example001", "identity_id": "idn_example001", "body": {"input": "夏についての短い詩を書いて"}} ``` | Field | Type | Required | Description | | ------------- | ------ | -------- | ------------------------------------------------------------------------- | | `custom_id` | string | Yes | 呼び出し元が定義する識別子。バッチ内で一意で、結果ファイルの行対応に使用します。 | | `template_id` | string | Yes | 実行に用いる Forward Template ID。 | | `identity_id` | string | Yes | 実行時に使用する Forward Identity ID。 | | `body` | object | Yes | Session に渡すリクエストボディ。構造は Template の定義に依存します。よくある形式: `{"input": "ユーザー入力"}`。 | **ファイルをアップロード:** ```bash theme={null} curl -X POST 'https://api.qoder.com/api/v1/cloud/files' \ -H "Authorization: Bearer $QODER_PAT" \ -F "file=@batch_input.jsonl" \ -F "purpose=session_resource" ``` `purpose` は必ず `session_resource` を指定してください。指定しない場合、ダウンロードに失敗する可能性があります。 返却された `id` が Create Batch リクエストの `input_file_id` になります。 ## Body parameters | Parameter | Type | Required | Description | | ------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------- | | `input_file_id` | string | Yes | Files API 経由でアップロードした JSONL ファイル ID。 | | `completion_window` | string | Yes | 完了ウィンドウ: `24h` / `48h` / `72h`。期限を過ぎるとバッチは `expired` に遷移します。 | | `metadata` | object | No | 呼び出し元のメタデータ。最大 16 個の key、value は任意の JSON 型、シリアライズ後 2KB 以下、key は 64 文字以下、NUL (U+0000) は含められません。 | ## Example request ```bash theme={null} curl -s -X POST 'https://api.qoder.com/api/v1/forward/batches' \ -H "Authorization: Bearer $QODER_PAT" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: idem_batch_001" \ -d '{ "input_file_id": "file_input001", "completion_window": "24h", "metadata": { "source": "data_pipeline", "job_id": "12345" } }' ``` ## Example response **HTTP 200 OK** ```json theme={null} { "id": "batch_example001", "object": "batch", "status": "validating", "input_file_id": "file_input001", "completion_window": "24h", "created_at": "2026-07-07T07:25:01Z", "expires_at": "2026-07-08T07:25:01Z", "request_counts": { "total": 0, "pending": 0, "running": 0, "completed": 0, "failed": 0, "cancelled": 0, "expired": 0 }, "usage": null } ``` 作成直後のバッチは `validating` になり、検証に通ると `queued` に遷移します。`output_file_id` / `error_file_id` はバッチが終端状態に達した後にのみ返され、作成レスポンスでは省略されます。 ## Response fields | Field | Type | Description | | ------------------- | ----------- | ---------------------------------------- | | `id` | string | バッチ ID。プレフィックスは `batch_`。 | | `object` | string | 常に `batch`。 | | `status` | string | バッチステータス。下記のステータス表を参照。 | | `input_file_id` | string | 入力 JSONL ファイル ID。 | | `completion_window` | string | 完了ウィンドウ: `24h` / `48h` / `72h`。 | | `created_at` | string | 作成時刻。RFC 3339。 | | `expires_at` | string | 有効期限。`created_at` + `completion_window`。 | | `request_counts` | object | タスクカウンタの集計値。 | | `usage` | object/null | 予約フィールド。v1 では常に `null`。 | | `metadata` | object | 呼び出し元のメタデータ。 | ### バッチステータス | Status | Description | Type | | ------------ | --------------------------- | ---- | | `validating` | 入力ファイルと JSONL 行を検証中。 | 非終端 | | `queued` | 検証に通過。オフピーク時間帯を待機中。 | 非終端 | | `processing` | タスク実行中。 | 非終端 | | `cancelling` | 取消処理中。実行中タスクの終了を待機中。 | 非終端 | | `expiring` | 期限切れ処理中。実行中タスクの終了を待機中。 | 非終端 | | `finalizing` | 出力ファイルを生成中。 | 非終端 | | `completed` | すべてのタスクが完了し、出力ファイルが生成済み。 | 終端 | | `failed` | 入力ファイルの検証失敗または回復不能なシステムエラー。 | 終端 | | `cancelled` | ユーザーが取り消し。 | 終端 | | `expired` | `completion_window` が経過。 | 終端 | ### Request counts | Field | Type | Description | | ----------- | ------- | -------------------- | | `total` | integer | 検証失敗行を含む総行数。 | | `pending` | integer | 実行待ちの行数。 | | `running` | integer | 実行中の行数。 | | `completed` | integer | 成功で終了した行数。 | | `failed` | integer | 永続的に失敗した行数（検証失敗を含む）。 | | `cancelled` | integer | 取消で終了した行数。 | | `expired` | integer | 期限切れで終了した行数。 | `total = pending + running + completed + failed + cancelled + expired` は常に成立します。 ## 検証ルール Create Batch は次のエラーを事前に検出し、キューには入れません。 * JSON パース失敗 → 当該行は `failed` として記録 * 必須フィールドの欠落 → 当該行は `failed` として記録 * `custom_id` の重複 → 当該行は `failed` として記録 * ツール権限ポリシーが `always_ask` / `always_deny` → 当該行は `failed` として記録（無人実行では許可されません） 行単位の検証失敗は他の行の実行を阻害せず、まとめて `error.jsonl` に書き出されます。 ## Error codes | HTTP | Type | Code | Trigger | | ---- | ----------------------- | ------------------------- | ------------------------------------------------------------- | | 400 | `invalid_request_error` | `invalid_request` | `input_file_id` の欠落、不正な `completion_window`、`metadata` サイズ超過。 | | 429 | `rate_limit_error` | `rate_limit_exceeded` | 未完了バッチ数が上限に達しています。 | | 401 | `authentication_error` | `authentication_required` | PAT が無効または期限切れです。 | ## Notes * 1 バッチあたり最大 10,000 行の JSONL に対応します。 * グローバル同時実行数は 50 タスクが上限です。 * スケジュールはオフピーク時間帯（デフォルト 22:00〜08:00、サーバー側で設定可能）で実行されます。 * バッチ作成後は `GET /api/v1/forward/batches/{batch_id}` をポーリングして終端状態を確認してください。 ## Related