Skip to main content
Batches

バッチを取得

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

GET /api/v1/forward/batches/{batch_id} バッチオブジェクトの全体を返します。現在のタスクカウンタと、終端状態到達後は出力ファイル ID も含まれます。 Create Batch のレスポンス後、この API をポーリングすることで、リソースの事前検証、キュー待ち、実行、終端結果を確認できます。validating 状態のタスクはすでに永続化されていますが、まだ実行キューには入っていません。

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT または SAT>

Path parameters

ParameterTypeRequiredDescription
batch_idstringYesバッチ ID。

Example request

curl -s -X GET 'https://api.qoder.com/api/v1/forward/batches/batch_completed001' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Example response

HTTP 200 OK 
{
  "id": "batch_completed001",
  "object": "batch",
  "status": "completed",
  "input_file_id": "file_input001",
  "output_file_id": "file_output001",
  "completion_window": "24h",
  "ignore_idle_window": false,
  "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": {
    "total_credits": 5.28
  }
}

Response fields

FieldTypeDescription
idstringバッチ ID。プレフィックスは batch_。
objectstring常に batch。
statusstringバッチステータス。
input_file_idstring入力 JSONL ファイル ID。
output_file_idstring成功行の結果ファイル ID。生成前は省略されます。
error_file_idstring失敗行の結果ファイル ID。失敗行がない場合は省略されます。
completion_windowstring完了ウィンドウ。
ignore_idle_windowboolean常に返されます。アイドルウィンドウを無視するかどうかを示します。過去の Batch、および作成時にこのフィールドを省略した Batch では false です。
queue_reasonstring現在のキュー待ち理由を示す任意の動的スナップショット。validating または queued の場合にのみ返ることがあります。
created_atstring作成時刻。RFC 3339。
expires_atstring有効期限。
request_countsobjectタスクカウンタの集計値。
usageobject/null永続化済みサブタスクの現在の使用量集計。有効な使用量がない場合は null。非終端 Batch では現時点の部分集計を、終端 Batch では最終集計を返します。
usage.total_creditsnumber各サブタスクの最終または現在の CAS Session の total_credits 合計。単位は CAS Credit であり、token 数や金額ではありません。明示的なゼロ値は保持されます。
metadataobject呼び出し元のメタデータ。
error_messagestringバッチ単位のエラーメッセージ。failed の場合のみ返されます。

ステータスとカウンタ

リソースに関する通常のステータス遷移は次のとおりです。 
validating → queued → processing → finalizing → completed
  • validating: JSONL 構造の同期チェックと既存の無人実行ポリシーチェックが完了し、Template/Identity の有効なリソースとファイルリソースをバックグラウンドで検証しています。Scheduler はこの状態の Batch を起動しません。
  • queued: リソースの事前検証が完了し、実行可能なタスクが存在します。アイドルウィンドウと同時実行枠を待っています。
  • processing: Scheduler が queued → processing のゲートを通過し、実行可能な pending タスクだけがキューに入ります。
  • 事前検証ですべてのタスクが失敗した場合、Session を作成せずに validating から直接 finalizing に移行します。
request_counts は現在の永続化済みスナップショットで、常に次の式を満たします。 
total = pending + running + completed + failed + cancelled + expired
validating 状態の pending は、受け付け済みでリソースの事前検証を待っているタスクを示し、すでにキューに入ったことを意味しません。非同期の事前検証で無効なリソースが見つかると、pending が減り、同じ数だけ failed が増えます。total は変わりません。 タスク単位のリソースエラーによって Batch 全体が failed になることはありません。失敗したタスクも output/error ファイルに含まれます。入力ファイルを読み取れない、永続化に失敗した、リソース検証処理を復旧できないなど、Batch 単位のエラーだけが Batch の failed 状態と error_message を生成します。

スケジューリングフィールド

owner は認証情報に対応するビジネス上の所有範囲です。PAT は現在のユーザー単位、管理者 SAT は organization と workspace の組み合わせで判定されます。 ignore_idle_window=true は Batch をアイドルウィンドウ外でも実行対象にしますが、即時実行や高い優先度を意味しません。同一 owner の排他制御、グローバル Batch 容量、グローバル Task 容量、validating → queued ゲート、FIFO 順序は引き続き適用されます。アイドルウィンドウ内では、通常の Batch とウィンドウを無視する Batch が created_at と ID に基づく同じ FIFO 順序を共有し、ウィンドウを無視しても順番は繰り上がりません。completion_window は引き続き created_at から起算され、検証、キュー待ち、実行の時間を含みます。延長やリセットはされません。 queue_reason は読み取り時点の動的スナップショットで、レスポンス直後に変わる可能性があります。スナップショットの読み込みに失敗した場合は省略されますが、詳細 API の成功には影響しません。次の優先順で最初に一致した理由が返されます。
優先度値意味
1idle_window現在がアイドルウィンドウ外で、この Batch がウィンドウを無視する設定ではありません。
2owner_processing同じ owner の別の Batch がすでに processing です。
3global_capacityグローバルの processing Batch 数が容量上限に達しています。
4scheduler_pendingBatch は queued で、最初の 3 条件には該当せず、Scheduler の起動を待っています。
validating では、最初の 3 つの確定済み外部ブロッカーだけが返ります。該当しない場合は省略され、scheduler_pending は返りません。processing、finalizing、cancelling、expiring、すべての終端状態では queue_reason が省略されます。グローバル容量が上限に達していても Create Batch は validating を返せます。その後の待機理由は global_capacity で表されます。

Error codes

HTTPTypeCodeTrigger
404not_found_errorbatch_not_foundバッチが存在しない、または他ユーザーのものです。
401authentication_errorauthentication_requiredPAT または SAT が無効、もしくは期限切れです。

Notes

  • 他ユーザーのバッチにアクセスすると 404 batch_not_found が返ります。
  • 404 batch_not_found は、Batch が存在しない場合と現在の呼び出し元から見えない場合を区別しません。クライアントはこれを根拠にリソースの所有者を推測しないでください。ファイルリソースの事前検証で発生した 404 も、安全な config_error として処理されます。
  • クライアントはこの API をポーリングして、バッチが終端状態（completed / failed / cancelled / expired）に達したかどうかを確認してください。

バッチの一覧取得

出力ファイルの取得

はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス