Loading docs
API & Evidence
Runs API
Understand the public product contract for creating, tracking, exporting, and reviewing quantum workflow runs.
Updated June 3, 2026QFlow StudioNormal userTeacher
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.
Purpose
Understand the public product contract for creating, tracking, exporting, and reviewing quantum workflow runs.
Where it fits
This page belongs to the API & Evidence section and should be read with the related pages listed at the end.
Review boundary
Use screenshots and notes to explain product behavior without exposing private credentials, admin state, or customer data.
Request shape
A run request should identify the workflow record, execution mode, provider or simulator route, shot count, and source snapshot. The authenticated user and private provider credentials are resolved server-side.
Example fields: workflowId, mode, providerId, deviceId, shots, sourceKind, circuitOperations, routeRationale, evidenceRequested.
workflowId
mode
providerId
shots
source snapshot
evidence flag
Response shape
A run response should expose status, run ID, timestamps, route summary, result pointer, counts or error payload, and evidence link when available.
Failed runs remain useful evidence. Preserve validation errors, provider readiness problems, unsupported-operation messages, and retry context.
queued
running
completed
failed
retried
exported
Auth, errors, and limits
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.
auth required
role checked
provider credentials sealed
limits explicit
errors retained
Next pages
Run workflows
Understand run feedback, simulator and hardware execution paths, queue context, and safe retry behavior.
Results & evidence
Use run history, evidence packets, certificates, and approved shares without exposing private workspace data.
Evidence manifest
Define the evidence packet manifest that connects workflow, source, route, counts, trace, exports, and private-field exclusions.