Flowintent / proof
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.
This page belongs to the API & Evidence section and should be read with the related pages listed at the end.
Use screenshots and notes to explain product behavior without exposing private credentials, admin state, or customer data.
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)
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). The source snapshot is taken from the saved workflow server-side.
{"workflowId": "cmbw1f2k80001abcd1234efgh","mode": "simulation","shots": 1024,"noiseModel": "ideal","wait": false}
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}}
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." }
Understand run feedback, simulator and hardware execution paths, queue context, and safe retry behavior.
Use run history, evidence packets, approved shares, and JSON/CSV exports without exposing private workspace data.
Define the evidence packet manifest that connects workflow, source, route, counts, trace, exports, and private-field exclusions.