completed, failed, or cancelled returns the
current state with HTTP 200, not an error. Safe to call from a poller
that’s racing against /tasks/query.
When to use
- User changed their mind — they hit “cancel” in your UI mid-render
- Cost ceiling tripped — your account just hit a soft credit cap and you want to stop in-flight work
- Stuck
pending— the task has been queued for unusually long; cancel and resubmit with different params
Request
By task_id (path-param form, primary)
By out_task_id (body form, fallback)
When you only have the idempotency key handy:Body
The body is only required for the out_task_id form.
Exactly one identifier must resolve. Sending both
task_id and
out_task_id, or neither, returns 400 invalid_param. The
path-param wins over task_id in the body if both are present.
Response
Identical shape to/tasks/query — the task in its
post-cancel state.
200 as “the task is no longer
in-flight” without branching on race conditions.
Billing semantics
For confidence on the running-state refund, inspect
credits_used
after the cancel returns. If absent, no charge; if present, that’s
the final amount.
Errors
Idempotency
Cancel is idempotent on terminal tasks: calling cancel on acompleted / failed / cancelled task returns the current state
with HTTP 200, not an error. This is intentional — clients polling
/tasks/query in parallel with a cancel button shouldn’t have to
branch on “did the task finish a millisecond before my cancel landed”.
Pricing
The cancel call itself is free. Refund of anycredits_used happens
during the cancel, not after.