Skip to main content
Batches

Batch サブタスクを取得

GET /api/v1/forward/batches/{batch_id}/tasks Batch 内の各タスクのステータス、結果概要、エラー、成果物、使用量をページ単位で取得します。Batch がどの状態でも呼び出せます。現在の PAT ユーザーが所有する Batch のサブタスクのみを返します。

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT または SAT>

Path parameters

ParameterTypeRequiredDescription
batch_idstringYesBatch ID。

Query parameters

ParameterTypeRequiredDefaultDescription
statusstringNo-タスクステータスで絞り込みます：pending、running、completed、failed、cancelled、expired。
custom_idstringNo-呼び出し元が指定したタスク識別子による完全一致フィルター。単一値のみをサポートし、一致しない場合は空のリストを返します。
limitintegerNo20ページサイズ。最大 100。
after_idstringNo-次ページのカーソル。前ページのレスポンスの last_id を渡します。カーソルは現在の Batch に属している必要があります。

Example request

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

Example response

HTTP 200 OK 
{
  "object": "list",
  "data": [
    {
      "custom_id": "task-001",
      "status": "completed",
      "started_at": "2026-08-06T14:01:03Z",
      "completed_at": "2026-08-06T14:03:41Z",
      "output_summary": "report generated",
      "usage": {
        "total_credits": 2.75
      },
      "artifacts": [
        {
          "file_id": "file_abc",
          "name": "report.xlsx",
          "size": 20480,
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        }
      ]
    },
    {
      "custom_id": "task-002",
      "status": "failed",
      "started_at": "2026-08-06T14:01:03Z",
      "completed_at": "2026-08-06T14:01:20Z",
      "error": {
        "code": "session_error",
        "message": "sandbox terminated unexpectedly"
      },
      "usage": {
        "total_credits": 0.5
      },
      "artifacts": []
    }
  ],
  "has_more": true,
  "first_id": "task-001",
  "last_id": "task-002"
}

Response fields

FieldTypeDescription
objectstring常に list。
dataarray現在のページに含まれる Batch Task オブジェクト。
data[].custom_idstring呼び出し元が指定したタスク識別子。現在のバージョンでは公開ページネーションカーソルとしても使用します。
data[].statusstringタスクステータス。Batch の request_counts の明細ステータスと同じ定義です。
data[].started_atstring永続化された最終実行試行の開始時刻（RFC 3339 UTC）。未開始の場合は省略されます。
data[].completed_atstringタスク完了時刻（RFC 3339 UTC）。未完了の場合は省略されます。
data[].output_summarystring最終レスポンステキスト。最大 500 Unicode 文字。結果がない場合は省略されます。
data[].errorobjectfailed タスクにのみ返され、code と message を含みます。
data[].artifactsarray配信済みの成果物。成果物がない場合は空配列を返します。
data[].usageobject最終または現在の CAS Session の使用量。CAS が有効な使用量を返していない場合は省略されます。
data[].usage.total_creditsnumberCAS Session の累積 Credit 消費量。token 数や金額ではありません。明示的なゼロ値は保持されます。
first_idstring現在のページの最初のタスクの custom_id。
last_idstring現在のページの最後のタスクの custom_id。
has_morebooleanさらにタスクがあるかどうか。
一時的なエラーの再試行では、タスク用に新しい CAS Session が作成されます。そのため、usage は最終または現在の Session のみを表し、置き換えられた過去の Session 使用量は加算されません。

Error codes

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_requeststatus、limit、または after_id が不正です。
404not_found_errorbatch_not_foundBatch が存在しない、他のユーザーに属している、または結果ファイルの 30 日間のクリーンアップが完了しています。
401authentication_errorauthentication_requiredPAT または SAT が無効または期限切れです。

Notes

  • has_more=true の場合は、last_id をそのまま次のリクエストの after_id として渡します。
  • 成果物のダウンロードには Files API を再利用します。Batch 専用の成果物ダウンロードエンドポイントはありません。

Batch を取得

出力ファイルを取得

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