Skip to main content
POST
Cancel a batch

Authorizations

Authorization
string
header
required

A long-lived, privileged API key (ek_... prefix), minted once from the dashboard. Intended for trusted server-side use only; never expose it in client-side code. Send as Authorization: Bearer ek_.... Required by every Calls, Batches, Agents, Tools, MCP Servers, Documents, and Realtime route.

Path Parameters

batch_id
string
required

Response

Successful Response

KNOWN IMPRECISION: this should be a discriminated union keyed on status, not one flat object with every non-status field optional. The OpenAPI schema currently can't express "scheduled_at and eligible only appear together with retry_scheduled; retried only appears with running"; every actual response still validates correctly, but a generated SDK's return type can't tell from the shape alone which fields accompany which status. Fine for now; revisit with a oneOf/discriminator (e.g. three response models keyed off status) if that ambiguity ever becomes an actual integration pain point rather than a theoretical one.

Shared by both batch cancel and retry. Outcome -> populated fields: "canceled" (cancel; no extra fields), "retry_scheduled" (retry, scheduled for later; scheduled_at + eligible), "running" (retry, fired immediately; retried).

status
enum<string>
required
Available options:
canceled,
retry_scheduled,
running
scheduled_at
string | null
eligible
integer | null
retried
integer | null