Cancel a run

There is no public cancel endpoint. The admin-only POST /v1/admin/runs//cancellation transitions a non-terminal run to cancelled. When to use it, when not to.

Admin-only endpoint. POST /v1/admin/runs/{run_id}/cancellation requires a service key (rf_svc_*) with admin scope. Inference keys (rf_live_*) get 401. There is intentionally no public per-run cancel.

Why there’s no public cancel

Almost every Runflow model completes in under 60 seconds. By the time a caller decides to cancel, the run is usually already finishing or about to bill anyway. Adding a public cancel surfaces race conditions (cancel-after-success) and partial-charge ambiguity without saving meaningful time or money. So the API ships without one.

The admin endpoint exists for operational override: shutting down a stuck run, responding to an abuse report, or honoring a customer ticket that asks for one specific run to be killed.

When to use it

• A run is stuck in queued or running longer than the model’s typical envelope and the customer needs the slot freed for retries.
• You are an org admin processing a support ticket asking to cancel a specific run.
• You are responding to an abuse pattern and want to terminate the offending run while you investigate the key.

If you’re a normal API caller and just want to stop polling, drop the run; the in-flight inference will complete on its own and any callback will silently fail at your end. Cancel adds no value in that case.

Behavior

POST /v1/admin/runs/{run_id}/cancellation atomically transitions a non-terminal run to cancelled and queues a run.cancelled audit side effect.

• Idempotent on terminal runs. Hitting it on an already-succeeded / failed / cancelled run returns the run unchanged with 200 OK. No audit log entry, no callback re-fire.
• 201 Created on a real cancellation transition. The status-code difference lets audit-tailers distinguish “I caused this” from “someone got there first.”
• Does not abort the in-flight inference. The compute job keeps running on the provider side. Late callbacks land on the now-cancelled run and are silently dropped by the terminal-state guard.
• Billing follows the underlying job. Cancellation does not auto-refund; the run bills whatever the provider charged for the work performed up to the cancel.

Request

curl -X POST "https://api.runflow.io/v1/admin/runs/{run_id}/cancellation" \
  -H "Authorization: Bearer $RUNFLOW_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "customer ticket #4821 - duplicate submission" }'

Body is optional; the only field is reason:

Field	Type	Required	Notes
reason	string | null	no	3-500 chars. Stored in audit_log.meta.reason. Strongly encouraged for cross-org admin overrides so the audit trail tells the story later.

Response

Both 200 and 201 return the post-cancel Run object (same shape as GET /v1/runs/{id}). Inspect status_code to confirm:

{
  "id": "01J0...",
  "status_code": "canceled",
  "model": "runflow/background-removal",
  "completed_at": "2026-05-23T10:42:11.000+00:00"
}

Note the spelling: run records use US canceled; webhook event names use UK cancelled. Both literals are stable.

Errors

Code	Cause	Action
401	Missing or non-admin key.	Use a service key (rf_svc_*) with admin scope. Inference keys are rejected.
403	PERMISSION_DENIED or EMAIL_NOT_VERIFIED.	Check the code field in the response body.
404	Run id not found in your reachable orgs.	Confirm the id and the org-scope of your admin key.
409	State invariant violated (e.g. self_action_forbidden).	Inspect errors[0].type.
422	reason failed validation (under 3 chars or all whitespace).	Send a longer reason or omit the field.

Related

Runs

Lifecycle, statuses, polling.

Callbacks

Note: late callbacks on cancelled runs are dropped.

Authentication

Service vs inference keys.

Errors

Status codes and error envelope.