Jobs

Jobs are the unit of execution in QCOS. A job may run on a simulator, a GPU/HPC target or a QPU provider. The canonical door is /api/v1/runtime/jobs.

Submit a circuit

curl -X POST "$QCOS_API_URL/api/v1/runtime/jobs" \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "backend_id": "simulator_aer",
    "shots": 1024,
    "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[1]; creg c[1]; h q[0]; measure q[0] -> c[0];"
  }'

Request fields: backend_id (required), qasm or algorithm, shots (default 1024), optional session_id, qec_config, dataset_id, metadata, confirm_cost. Add ?dry_run=true to get the estimate and validation result without executing. For long-running workloads use the async door: POST /api/v1/runtime/jobs/async.

Poll a job

curl "$QCOS_API_URL/api/v1/runtime/jobs/job_abc123" \
  -H "Authorization: Bearer $QCOS_API_KEY"

The job payload carries status, estimated_cost_usd, cost_basis, approval_required, result (when complete) and artifacts. Server-sent progress events: GET /api/v1/runtime/jobs/{job_id}/events.

Approve a gated job

Real-QPU jobs, jobs with QEC enabled and estimates at or above $1.00 come back with "approval_required": true and an approval_token:

curl -X POST "$QCOS_API_URL/api/v1/runtime/jobs/job_abc123/approve" \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approval_token": "..."}'

Retrieve results and artifacts

Results are embedded in the job payload once status is completed. Every artifact — including the sealed execution evidence — is listed at:

curl "$QCOS_API_URL/api/v1/runtime/jobs/job_abc123/artifacts" \
  -H "Authorization: Bearer $QCOS_API_KEY"

curl "$QCOS_API_URL/api/v1/runtime/jobs/job_abc123/artifacts/execution_evidence.json/raw" \
  -H "Authorization: Bearer $QCOS_API_KEY"

Cancel a job

curl -X DELETE "$QCOS_API_URL/api/v1/runtime/jobs/job_abc123" \
  -H "Authorization: Bearer $QCOS_API_KEY"

The response’s provider_abort field tells you what actually happened upstream: not_dispatched (never reached the provider), acknowledged (provider abort requested) or unsupported — in which case the circuit runs to completion on the provider and consumes billable shots; a warning field is present exactly then. Cancelling an already-finished job returns 409.

Job states

State	Meaning
`dry_run`	Estimate/validation only — nothing executed
`approval_required`	Cost or QPU policy needs confirmation
`approved`	Approval token accepted
`queued`	Accepted and waiting
`validating`	Circuit validation in progress
`estimating_cost`	Technical cost estimation
`submitted_to_provider`	Handed to the backend provider
`running`	Executing
`postprocessing`	Mitigation/QEC/artifact generation
`completed`	Results available
`failed`	Execution failed
`cancelled`	Cancelled by user or policy

Migrating from the legacy doors

Legacy (deprecated)	Use instead
`POST /api/v1/execute`, `POST /execute`	`POST /api/v1/runtime/jobs`
`POST /api/v1/jobs`, `POST /v1/jobs`	`POST /api/v1/runtime/jobs`
`GET /api/v1/status/{id}`	`GET /api/v1/runtime/jobs/{id}`
`GET /api/v1/results/{id}`	`GET /api/v1/runtime/jobs/{id}` (`result` field)
`GET /api/v1/jobs/{id}/artifacts`	`GET /api/v1/runtime/jobs/{id}/artifacts`

Legacy doors still answer with deprecation headers, but new fields (sessions, primitives, approval flow, sealed evidence artifacts) exist only on /api/v1/runtime/*. Field renames: backend → backend_id, circuit/circuit_qasm → qasm.

​Jobs

​Submit a circuit

​Poll a job

​Approve a gated job

​Retrieve results and artifacts

​Cancel a job

​Job states

​Migrating from the legacy doors