POST /api/v1/forward/batches
Forward はリクエスト内で入力ファイルを読み取り、JSONL 構造を解析して初期タスク数を永続化した後、validating を返します。ファイルリソースなどの外部依存関係はバックグラウンドで事前検証され、検証を通過したタスクだけがスケジューリング待ちに進めます。デフォルトでは、Batch はアイドルウィンドウ内でのみスケジューリング対象になります。ignore_idle_window=true を指定すると、この時間帯の制限を受けません。完了後は output.jsonl が生成され、失敗行がある場合は error.jsonl も生成されます。
| Header | Required | Description |
|---|
Authorization | Yes | Bearer <PAT または SAT> |
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":"レポートを分析する","resources":[{"type":"file","file_id":"opaque-report-id","mount_path":"/data/input/report.pdf"}]}}
{"custom_id":"task-002","template_id":"tmpl_example001","identity_id":"idn_example001","body":{"input":"会議記録を要約する","resources":[{"type":"file","file_id":"opaque-notes-id"}]}}
| 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 に渡すリクエストボディ。現在は必須の input と任意の resources を含みます。 |
body.input | string | Yes | このタスクから Agent に送信する入力。 |
body.resources | array | No | このタスクに追加するファイルリソース。省略するか空の配列を渡すと、行単位のファイルは追加されません。 |
body.resources[].type | string | Yes | リソースタイプ。現在は file のみを指定できます。欠落または異なる値を指定すると、その行は invalid_line になります。 |
body.resources[].file_id | string | Yes | Files API が返したファイル ID。不透明な文字列として扱われ、トリム後に空であってはなりません。 |
body.resources[].mount_path | string | No | Agent コンテナ内のマウントパス。正規化された絶対パスである必要があります。省略すると、ファイル名から /data/workspace/<filename> が生成されます。 |
resources 要素は JSON object で、type、file_id、mount_path 以外のフィールドを含めることはできません。フィールド型の誤り、未知のフィールド、相対パス、.. を含む正規化されていないパス、制御文字があると、リソースを黙って無視せず、行全体が invalid_line になります。
行単位のファイルは Template と Identity の有効なリソースに追加され、既存のリソースを置き換えません。file_id またはマウントパスの重複、Template、Identity、リポジトリリソースとのパス重複がある場合、該当タスクは config_error で失敗します。
ファイルは Batch を作成する呼び出し元からアクセス可能で、マウントできる ready 状態である必要があります。Batch はファイルをコピーまたはロックせず、ファイルの有効期間も延長しません。事前検証後にファイルが削除、失効、または変更された場合、Session 作成時に再検証され、タスクが失敗することがあります。
curl -X POST 'https://api.qoder.com/api/v1/cloud/files' \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-F "file=@batch_input.jsonl" \
-F "purpose=session_resource"
Batch 入力ファイルでは purpose=session_resource が必須です。このフィールドを省略すると、Files API はファイルを user_upload として保存します。CAS はこの種のファイルのサーバー側ダウンロードを許可しないため、Create Batch は 400 invalid_input_file を返します。
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) は含められません。 |
ignore_idle_window | boolean | No | アイドルウィンドウを無視するかどうか。省略時のデフォルトは false です。JSON boolean の true または false のみを受け付け、文字列や数値を暗黙に変換しません。 |
ignore_idle_window は厳密な boolean フィールドです。null、"true"、1、[]、{} を指定すると、HTTP 400 invalid_request_error / invalid_request とエラーメッセージ ignore_idle_window must be a boolean が返ります。
Example requests
通常の Batch（デフォルトでアイドルウィンドウを使用）
ignore_idle_window の省略は、false の明示的な指定と同じです。
curl -s -X POST 'https://api.qoder.com/api/v1/forward/batches' \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"input_file_id": "file_input001",
"completion_window": "24h"
}'
アイドルウィンドウを無視する Batch
curl -s -X POST 'https://api.qoder.com/api/v1/forward/batches' \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-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"
},
"ignore_idle_window": true
}'
Example response
HTTP 200 OK
{
"id": "batch_example001",
"object": "batch",
"status": "validating",
"input_file_id": "file_input001",
"completion_window": "24h",
"ignore_idle_window": true,
"created_at": "2026-07-07T07:25:01Z",
"expires_at": "2026-07-08T07:25:01Z",
"request_counts": {
"total": 2,
"pending": 2,
"running": 0,
"completed": 0,
"failed": 0,
"cancelled": 0,
"expired": 0
},
"usage": null
}
validating のスナップショットを返します。そのため、request_counts にはゼロのプレースホルダーではなく、実際の初期件数が含まれます。個別のファイル検索とリソース統合時の競合チェックはバックグラウンドで実行され、合格後にのみ Batch は queued に移行できます。output_file_id と error_file_id は Batch が終端状態に達した後にのみ現れ、作成レスポンスでは省略されます。
100 行のうち 3 行が同期的な構造解析で失敗した場合、作成レスポンスは total=100、pending=97、failed=3 になります。その後、バックグラウンドのリソース事前検証により、一部のタスクが pending から failed に移ることがありますが、カウンタの不変条件は常に成立します。
グローバル容量が上限に達している場合
グローバルの processing Batch が容量上限に達していても、Create Batch は HTTP 200 OK と validating を返します。現在の待機理由は動的スナップショットで示されます。
{
"id": "batch_capacity_waiting001",
"object": "batch",
"status": "validating",
"input_file_id": "file_input001",
"completion_window": "24h",
"ignore_idle_window": true,
"queue_reason": "global_capacity",
"created_at": "2026-07-07T07:25:01Z",
"expires_at": "2026-07-08T07:25:01Z",
"request_counts": {
"total": 2,
"pending": 2,
"running": 0,
"completed": 0,
"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。 |
completion_window | string | 完了ウィンドウ: 24h / 48h / 72h。 |
ignore_idle_window | boolean | 常に返されます。Batch がアイドルウィンドウを無視するかどうかを示します。過去の Batch、および作成時にこのフィールドを省略した Batch では false です。 |
queue_reason | string | 現在のキュー待ち理由を示す任意の動的スナップショット。validating または queued の場合にのみ返ることがあります。 |
created_at | string | 作成時刻。RFC 3339。 |
expires_at | string | 有効期限。created_at + completion_window。 |
request_counts | object | タスクカウンタの集計値。 |
usage | object/null | 作成レスポンスでは null。以降の Batch 詳細、一覧、キャンセルのレスポンスでは、少なくとも 1 つのサブタスクに有効な CAS Session 使用量がある場合、Credit の集計を返します。 |
usage.total_credits | number | 永続化済みサブタスクの total_credits の合計。単位は CAS Credit であり、token 数や金額ではありません。明示的なゼロ値は保持されます。 |
metadata | object | 呼び出し元のメタデータ。 |
バッチステータス
| Status | Description | Type |
|---|
validating | JSONL 行と同期構成チェックの結果が永続化され、有効な構成とファイルリソースをバックグラウンドで事前検証しています。タスクはまだ実行キューに入っていません。 | 非終端 |
queued | リソースの事前検証が完了し、実行可能なタスクが存在します。アイドルウィンドウ、容量、owner の排他ルールに従って Scheduler が起動するのを待っています。 | 非終端 |
processing | タスク実行中。 | 非終端 |
cancelling | 取消処理中。実行中タスクの終了を待機中。 | 非終端 |
expiring | 期限切れ処理中。実行中タスクの終了を待機中。 | 非終端 |
finalizing | 出力ファイルを生成中。 | 非終端 |
completed | すべてのタスクが完了し、出力ファイルが生成済み。 | 終端 |
failed | 入力ファイルを読み取れない、永続化に失敗した、リソース検証処理を復旧できないなど、Batch 単位のエラー。 | 終端 |
cancelled | ユーザーが取り消し。 | 終端 |
expired | completion_window が経過。 | 終端 |
スケジューリングとキュー待ち理由
owner は認証情報に対応するビジネス上の所有範囲です。PAT は現在のユーザー単位、管理者 SAT は organization と workspace の組み合わせで判定されます。
ignore_idle_window=true が変更するのは Batch の時間帯に関する実行資格だけで、即時実行や高い優先度を意味しません。次のルールは引き続き適用されます。
- 同じ owner で同時に
processing にできる Batch は 1 つだけです。
- グローバル Batch 容量とグローバル Task 容量は変わりません。
- リソース検証を完了し、
validating から queued に移行した Batch だけが起動対象になります。
- アイドルウィンドウ内では、通常の Batch とウィンドウを無視する Batch が
created_at と ID に基づく同じ FIFO 順序を共有します。
completion_window は引き続き created_at から起算され、検証、キュー待ち、実行の時間を含みます。アイドルウィンドウを無視しても延長やリセットはされません。
queue_reason は読み取り時に計算される動的スナップショットです。レスポンス直後に変わる可能性があり、スナップショットを読み込めない場合は省略されますが、メイン API の成功には影響しません。次の優先順で最初に一致した値が返されます。
| 優先度 | 値 | 意味 |
|---|
| 1 | idle_window | 現在がアイドルウィンドウ外で、この Batch がウィンドウを無視する設定ではありません。 |
| 2 | owner_processing | 同じ owner の別の Batch がすでに processing です。 |
| 3 | global_capacity | グローバルの processing Batch 数が容量上限に達しています。 |
| 4 | scheduler_pending | Batch は queued で、最初の 3 条件には該当せず、Scheduler の起動を待っています。 |
queue_reason は validating と queued にのみ適用されます。validating では、最初の 3 つの確定済み外部ブロッカーだけが返ります。該当しない場合は省略され、scheduler_pending は返りません。processing、finalizing、cancelling、expiring、すべての終端状態では省略されます。
グローバル Batch 容量が上限に達していても、Create Batch は正常に validating を返せます。検証完了後も Batch はキュー待ちを続け、現在の待機理由として global_capacity を返します。
Request counts
| Field | Type | Description |
|---|
total | integer | 検証失敗行を含む総行数。 |
pending | integer | まだ実行を開始していない行数。Batch が validating の場合は、受け付け済みでリソースの事前検証を待っているタスクを示し、まだ実行キューには入っていません。 |
running | integer | 実行中の行数。 |
completed | integer | 成功で終了した行数。 |
failed | integer | 永続的に失敗した行数（検証失敗を含む）。 |
cancelled | integer | 取消で終了した行数。 |
expired | integer | 期限切れで終了した行数。 |
total = pending + running + completed + failed + cancelled + expired は常に成立します。
検証とキュー投入ゲート
Create Batch はリクエスト内で次の処理を同期的に実行します。
- 入力ファイルを読み取り、各 JSON 行を解析します。
- 必須フィールド、
custom_id の一意性、body.resources の構造を検証します。
- Template と Identity を解決し、既存の無人実行ツール権限ポリシーをチェックします。
- 同期検証を通過した行を
pending として保存し、失敗した行を invalid_line、config_error、または permission_denied の failed として保存します。
- 実際の初期
total、pending、failed 件数を永続化します。
レスポンス後、Forward は Batch 作成時の呼び出し元の権限で Template/Identity の有効なリソースをバックグラウンドで解決し、ファイル検索、デフォルトパス生成、統合後のリソース競合チェックを実行します。事前検証中、Batch は validating のままで、実行キューへの投入や Session の作成は行われません。事前検証が完了すると、次のように遷移します。
- 有効なタスクが残っている場合:
validating → queued → processing
- すべてのタスクが失敗した場合:
validating → finalizing → completed。結果ファイルが生成されます。
- 取消または期限切れが先に発生した場合: リソース検証によって Batch が再起動またはキュー投入されることはありません。
1 行の検証失敗が他の行をブロックすることはありません。失敗行は output.jsonl に残り、error.jsonl にも書き込まれます。Session が作成されていない場合は session_id を省略し、body.resources には元のリクエスト内容を保持します。
タスクエラーの分類
| Code | 意味 | リソース検索の再試行 |
|---|
invalid_line | JSONL 構造、リソースフィールド、type、file_id、または明示的なマウントパスが不正です。 | なし |
config_error | ファイルが 404/410 を返す、ready ではない、マウントできない、または統合後のリソースと競合しています。 | なし |
permission_denied | 上流サービスが明示的に 401/403 を返しました。 | なし |
transient_error | ファイル検索がタイムアウト、または 429/5xx を返し、最大 3 回のバックオフ再試行後も失敗しました。 | 最大 3 回 |
config_error を返します。明示的な 401/403 だけを permission_denied に分類します。
Error codes
| HTTP | Type | Code | Trigger |
|---|
| 400 | invalid_request_error | invalid_request | input_file_id の欠落、不正な completion_window、metadata サイズ超過、または ignore_idle_window が JSON boolean ではありません。 |
| 400 | invalid_request_error | invalid_input_file | Batch が入力ファイルをダウンロードできません。アップロード時に purpose=session_resource を指定してください。 |
| 409 | conflict_error | batch_already_processing | ignore_idle_window=true で、同じ owner にステータスが厳密に processing の Batch がすでに存在します。 |
| 429 | rate_limit_error | rate_limit_exceeded | 未完了バッチ数が上限に達しています。 |
| 401 | authentication_error | authentication_required | PAT または SAT が無効、もしくは期限切れです。 |
同一 owner の処理中 Batch との競合
リクエストが ignore_idle_window=true で、同じ owner にステータスが厳密に processing の Batch がすでに存在する場合に限り、Create Batch は HTTP 409 を返します。
{
"type": "error",
"request_id": "req_example001",
"error": {
"type": "conflict_error",
"code": "batch_already_processing",
"message": "Another Batch is already processing for this owner.",
"batch_id": "batch_existing001"
}
}
error.batch_id は、同じ owner で現在処理中の Batch ID です。この競合チェックは、未完了 Batch のクォータチェック、およびすべてのファイル処理や永続化の副作用より先に行われます。拒否されたリクエストは Batch や Task を作成せず、入力ファイルの読み取り、解析、検証も行わず、期限切れメッセージも送信しません。validating、queued、finalizing、cancelling、expiring、終端状態ではこの 409 は発生しません。
Notes
- 1 バッチあたり最大 10,000 行の JSONL に対応します。
- グローバル同時実行数は 50 タスクが上限です。
- デフォルトでは、アイドルウィンドウ（デフォルト 22:00〜08:00、サーバー側で設定可能）内でスケジュールされます。
ignore_idle_window=true が解除するのは、この時間帯の制限だけです。
- バッチ作成後は
GET /api/v1/forward/batches/{batch_id} をポーリングして終端状態を確認してください。
