Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runflow.io/llms.txt

Use this file to discover all available pages before exploring further.

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:
FieldTypeRequiredNotes
reasonstring | nullno3-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

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

Runs

Lifecycle, statuses, polling.

Callbacks

Note: late callbacks on cancelled runs are dropped.

Authentication

Service vs inference keys.

Errors

Status codes and error envelope.