Skip to main content
Batches

バッチを取消

実行中または待機中のバッチを取り消します。

POST /api/v1/forward/batches/{batch_id}/cancel 取消が発行されると、Forward はキューをドレインして pending タスクを cancelled にマークし、実行中の各タスクに対して CancelSession を呼び出します。

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT または SAT>
Idempotency-KeyNo安全でないリクエスト向けの任意のべき等性キー。

Path parameters

ParameterTypeRequiredDescription
batch_idstringYesバッチ ID。

Example request

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

Example response

HTTP 200 OK 
{
  "id": "batch_processing001",
  "object": "batch",
  "status": "cancelling",
  "input_file_id": "file_input002",
  "completion_window": "24h",
  "ignore_idle_window": true,
  "created_at": "2026-07-06T11:59:02Z",
  "expires_at": "2026-07-07T11:59:02Z",
  "request_counts": {
    "total": 10,
    "pending": 0,
    "running": 3,
    "completed": 7,
    "failed": 0,
    "cancelled": 0,
    "expired": 0
  },
  "usage": {
    "total_credits": 12.5
  }
}
レスポンスは取消発行時点のスナップショットです。実行中タスクが残っていれば status は中間状態の cancelling、残っていなければ直接 cancelled を返します。すでに終端状態にあるバッチはべき等に現在のオブジェクトを返します。usage は、その時点で永続化済みのサブタスクの CAS Credit 集計です。有効な使用量がまだない場合は null です。

Response fields

FieldTypeDescription
戻り値objectバッチオブジェクト。
Batch オブジェクトは常に ignore_idle_window を boolean で返します。取消によって永続化された値は変更されません。過去の Batch、および作成時にこのフィールドを省略した Batch では false です。汎用の Batch オブジェクトでは任意の string queue_reason が返る場合がありますが、取消に成功したレスポンスは cancelling または終端状態になるため、このフィールドは省略されます。

取消フロー

  1. 終端状態のバッチ: 200 をべき等に返し、操作は行いません。
  2. CAS がステータスを validating|queued|processing → cancelling に遷移させます。
  3. Redis キューをドレインし、pending タスクを一括で cancelled にマークします。
  4. 実行中の各タスクに対して CancelSession を呼び出します。
  5. 実行中タスクが残っていなければ即座に finalize を起動、残っていれば最後の CompleteTask が finalize を駆動します。

Error codes

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

Notes

  • 取消は非同期処理です。cancelling はリクエストが受理されたことを意味します。詳細をポーリングして終端状態を確認してください。
  • すでに終端状態のバッチへの取消はべき等で、200 を返します。

バッチを取得

出力ファイルの取得

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