Loading docs
Understand the public product contract for creating, tracking, exporting, and reviewing quantum workflow runs.
The runs API should be read as a workflow-record API, not as an isolated execution endpoint. A useful run carries workflow ID, provider route, simulator or hardware mode, source snapshot, status, and evidence destination.
Use this reference when designing integrations, support runbooks, or reviewer instructions that need the exact lifecycle without exposing private provider credentials.
Section 01
Run endpoints are session-authenticated and same-origin guarded: they serve the signed-in product UI and scripts that reuse a browser session. The authenticated user and private provider credentials are resolved server-side.
POST /api/runs Start a run for a workflow you ownGET /api/runs?workflowId={id} List your runs (optional limit={n})GET /api/runs/{id} Fetch one run recordGET /api/runs/{id}/stream Server-sent events until the run is terminalDELETE /api/runs/{id} Cancel a run (the record is kept as evidence)
Section 02
A run request identifies the workflow record, execution mode, shot count, and noise model. mode is one of simulation, dry-run, or hardware; hardware runs additionally require providerId (and usually device). Simulation requests may provide a 31-bit seed; when omitted, QFlow generates one and stores it with the run so counts can be reproduced. The source snapshot is taken from the saved workflow server-side.
{"workflowId": "cmbw1f2k80001abcd1234efgh","mode": "simulation","shots": 1024,"noiseModel": "ideal","seed": 20260813,"wait": false}
Section 03
Simulation runs are asynchronous by default: POST /api/runs answers 201 Created with the run still in status "queued" and execution continues detached. Poll GET /api/runs/{id} or subscribe to GET /api/runs/{id}/stream to follow it to a terminal status. Passing wait: true keeps the legacy inline behavior where the 201 response already carries the terminal run.
Dry-run requests validate inline and return immediately. Hardware requests submit to the provider inline and are then reconciled by background polling. Run status is one of queued, running, completed, failed, or cancelled.
Failed runs remain useful evidence. Validation errors, provider readiness problems, and unsupported-operation messages are preserved on the run record (errorMessage).
{"run": {"id": "cmbw1g9zq0003abcd5678ijkl","workflowId": "cmbw1f2k80001abcd1234efgh","workflowName": "Bell state baseline","mode": "simulation","status": "queued","providerId": "local","device": null,"shots": 1024,"noiseModel": "ideal","result": null,"errorMessage": null,"durationMs": null,"externalJobId": null,"shareToken": null,"metadata": {},"createdAt": "2026-06-12T09:30:00.000Z","startedAt": null,"completedAt": null}}
Section 04
Runs require an authenticated user and a workflow they are allowed to operate. Provider credentials are never sent from public docs or reviewer links.
Common errors include missing workflow, permission failure, unsupported provider submit path, invalid circuit shape, runner limit exceeded, provider quota failure, and timeout. Shot counts are capped per runner configuration; oversized requests fail schema validation with an explicit message.
// 401 — no authenticated session{ "error": "Unauthorized" }// 400 — schema validation failed (zod issues included){"error": "Invalid request.","issues": [{ "path": ["shots"], "message": "Python runner simulation shots must be between 1 and 300000." }]}// 404 — workflow does not exist or is not yours{ "error": "Workflow not found." }// 400 — run-level failure (message is the contract; code/details appear when available){ "error": "Hardware runs require a real provider." }