バッチを作成

POST /api/v1/forward/batches Forward が入力ファイルと JSONL 行フォーマットを検証したうえで、オフピーク時間帯に自動的にスケジュールされます。完了後は output.jsonl と error.jsonl がダウンロード用に生成されます。

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT>`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	No	安全でないリクエスト向けの任意のべき等性キー。

事前準備: 入力ファイルのアップロード

バッチを作成するには、まず JSONL 形式の入力ファイルを用意し、CAS Files API 経由でアップロードして file_id を取得します。 JSONL フォーマット: 1 行につき 1 個の JSON オブジェクトが 1 タスクを表します。

{"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": "ユーザー入力"}`。

ファイルをアップロード:

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

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

{
  "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} をポーリングして終端状態を確認してください。

はじめに

Agent の定義

Agent 環境の設定

Agent にタスクを委任する

Agent コンテキストの管理

ベストプラクティス

API リファレンス

バッチを作成

Headers

事前準備: 入力ファイルのアップロード

Body parameters

Example request

Example response

Response fields

バッチステータス

Request counts

検証ルール

Error codes

Notes

バッチを取得

バッチを取消

​Headers

​事前準備: 入力ファイルのアップロード

​Body parameters

​Example request

​Example response

​Response fields

​バッチステータス

​Request counts

​検証ルール

​Error codes

​Notes

​Related

バッチを取得

バッチを取消

Headers

事前準備: 入力ファイルのアップロード

Body parameters

Example request

Example response

Response fields

バッチステータス

Request counts

検証ルール

Error codes

Notes

Related