> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# バッチを取消

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

`POST /api/v1/forward/batches/{batch_id}/cancel`

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

## Headers

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

## Path parameters

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `batch_id` | string | Yes      | バッチ ID。     |

## Example request

```bash theme={null}
curl -s -X POST 'https://api.qoder.com/api/v1/forward/batches/batch_processing001/cancel' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "id": "batch_processing001",
  "object": "batch",
  "status": "cancelling",
  "input_file_id": "file_input002",
  "completion_window": "24h",
  "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": null
}
```

レスポンスは取消発行時点のスナップショットです。実行中タスクが残っていれば `status` は中間状態の `cancelling`、残っていなければ直接 `cancelled` を返します。すでに終端状態にあるバッチはべき等に現在のオブジェクトを返します。

## Response fields

| Field | Type   | Description |
| ----- | ------ | ----------- |
| 戻り値   | object | バッチオブジェクト。  |

## 取消フロー

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

## Error codes

| HTTP | Type                   | Code                      | Trigger                  |
| ---- | ---------------------- | ------------------------- | ------------------------ |
| 404  | `not_found_error`      | `batch_not_found`         | バッチが存在しない、または他ユーザーのものです。 |
| 401  | `authentication_error` | `authentication_required` | PAT が無効または期限切れです。        |

## Notes

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

## Related

<CardGroup cols={2}>
  <Card title="バッチを取得" icon="file-text" href="/ja/cloud-agents/api/forward/batches/get" />

  <Card title="出力ファイルの取得" icon="download" href="/ja/cloud-agents/api/forward/batches/get-output" />
</CardGroup>