Skip to main content
Batches

Cancel a batch

Cancel a batch that is running or waiting.

POST /api/v1/forward/batches/{batch_id}/cancel Once cancellation is initiated, Forward drains the queue, marks pending tasks as cancelled, and calls CancelSession on every running task.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Idempotency-KeyNoOptional idempotency key for unsafe requests.

Path parameters

ParameterTypeRequiredDescription
batch_idstringYesBatch 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
  }
}
The response is a snapshot at cancellation time: if running tasks remain, status is the intermediate cancelling; otherwise it is cancelled directly. Cancelling a batch already in a terminal state returns the current object idempotently. usage is the aggregate CAS Credit usage persisted for subtasks at that time. It is null when no valid usage is available yet.

Response fields

FieldTypeDescription
Return valueobjectBatch object.
The Batch object always returns ignore_idle_window as a boolean. Cancellation does not change its persisted value. Historical batches and batches created without this field use false. The general Batch object may include the optional string queue_reason, but a successful cancellation response has cancelling or a terminal status, so this field is omitted.

Cancellation flow

  1. Batch already in a terminal state: returns 200 idempotently, no operation performed.
  2. CAS transitions the status validating|queued|processing → cancelling.
  3. Drain the Redis queue and bulk-mark pending tasks as cancelled.
  4. Call CancelSession on each running task.
  5. If no running tasks remain, trigger finalize immediately; otherwise wait for the last CompleteTask to drive finalize.

Error codes

HTTPTypeCodeTrigger
404not_found_errorbatch_not_foundBatch does not exist or belongs to another user.
401authentication_errorauthentication_requiredPAT or SAT is invalid or expired.

Notes

  • Cancellation is asynchronous. A cancelling response means the request was accepted; poll the batch detail to confirm the terminal state.
  • Cancelling a batch already in a terminal state is idempotent and returns 200.

Get a batch

Get output file

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference