Every workload — quantum circuit, GPU job or CPU job — goes through the same endpoint: POST /api/v1/platform/execution/jobs. The platform authorizes the run, reserves its worst-case cost, submits it to the provider, then settles the actual cost and attaches an Evidence Bundle. This quickstart runs a two-qubit Bell circuit on the free statevector simulator (qcos.simulator.statevector) — real execution, zero cost.

Quickstart: Bell circuit over REST

Create an API key

In the console open API Keys → create a key (scope qcos:execute). Copy it — it is shown once.

export SQ_API_KEY=sq-live-...

Check what you can run

Every workspace gets the simulator plus the GPU/CPU tiers activated as its default catalog (real QPUs need entitlements). Listing your targets also activates that default catalog on first call:

curl -sS https://platform.softquantus.com/api/internal/v1/commerce/target-entitlements \
  -H "Authorization: Bearer $SQ_API_KEY"

(The CLI’s qcoscloud targets and the console’s Compute Console do the same.)

Submit the circuit

The circuit is OpenQASM 2.0, carried in the workload’s qasm field. Send an Idempotency-Key so a retried request never double-submits:

curl -sS -X POST https://platform.softquantus.com/api/v1/platform/execution/jobs \
  -H "Authorization: Bearer $SQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "target": "qcos.simulator.statevector",
    "execution_mode": "NATIVE",
    "workload": {
      "type": "QUANTUM_CIRCUIT",
      "shots": 1024,
      "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;"
    },
    "max_estimated_cost_usd": 5.00
  }'

The platform authorizes, reserves the worst-case cost (here 0 — the simulator is free) and returns the job:

{
  "job_id": "job_a1b2c3d4",
  "status": "CREDIT_RESERVED",
  "execution_mode": "NATIVE",
  "billing_mode": "PREPAID",
  "target_id": "qcos.simulator.statevector",
  "shots": 1024,
  "estimated_cost_usd": 0.0,
  "actual_cost_usd": null,
  "credits_remaining": 125.0,
  "result_verified": false
}

Poll until it settles

curl -sS https://platform.softquantus.com/api/v1/platform/execution/jobs/job_a1b2c3d4 \
  -H "Authorization: Bearer $SQ_API_KEY"

Poll until status is SETTLED. On a settled job actual_cost_usd is the real charge (here 0.0), usage_metrics reports shots and timing, and result_verified: true means the run completed and its result is pinned by hash.

Verify the run

curl -sS https://platform.softquantus.com/api/v1/platform/execution/jobs/job_a1b2c3d4/evidence \
  -H "Authorization: Bearer $SQ_API_KEY"

Returns the hash-pinned Evidence Bundle — how, where and with which parameters the run was produced. Available once settled (before that: 409 evidence_not_available_until_settled).

The same run with the Python SDK:

from qcoscloud import QCOSCloud

BELL = 'OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;'

qc = QCOSCloud()                          # reads QCOSCLOUD_API_KEY
job = qc.run("qcos.simulator.statevector", qasm=BELL, shots=1024)
print(qc.workload(job["job_id"])["status"])   # ... SETTLED

A QUANTUM_CIRCUIT workload must carry a circuit — qasm (OpenQASM 2/3) or artifact_uri. Submitting one without either is rejected up front with 422 quantum_circuit_missing, before any credit is reserved.

Reading the result

The Execution Plane job object carries status, cost, usage_metrics and the result hash (in the Evidence Bundle) — it does not embed raw measurement counts. For interactive circuit runs with counts returned directly, use the QCOS Sampler through the console proxy (requires the qcos:execute scope; this is also what the QCOS Compute Hub composer uses — counts come from QCOS, never synthesized in the browser):

curl -sS -X POST https://platform.softquantus.com/api/v1/platform/qcos/primitives/sampler \
  -H "Authorization: Bearer $SQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"backend_id": "simulator_aer", "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;", "shots": 1024}'

qasm and backend_id are required (400 otherwise); list backend ids with GET /api/v1/platform/qcos/backends. You can also price a circuit before running anything with POST /api/v1/platform/qcos/estimate.

The three workload shapes

QUANTUM_CIRCUIT — simulator or real QPU

{
  "target": "qcos.simulator.statevector",
  "execution_mode": "NATIVE",
  "instance_id": "optional — its plan decides billing",
  "workload": { "type": "QUANTUM_CIRCUIT", "shots": 1024, "qasm": "OPENQASM 2.0; ..." },
  "max_estimated_cost_usd": 5.00
}

Point target at a real device id to run the same circuit on hardware, metered per shot (IBM-class devices meter per second of runtime and additionally require max_runtime_seconds). execution_mode is NATIVE (default) or QCOS_OPTIMIZED — the latter applies QCOS transforms and requires an active QCOS license (403 qcos_license_required otherwise). See Backends & pricing.

GPU_JOB — on-demand NVIDIA GPU

Runs a container command on an on-demand GPU, billed per minute. A runtime bound is required (max_runtime_seconds; the worst case is reserved up front and the GPU is stopped when the reservation is exhausted):

{
  "target": "gpu.a100-80gb",
  "execution_mode": "NATIVE",
  "workload": {
    "type": "GPU_JOB",
    "kind": "job",
    "gpu": "a100-80gb",
    "num_gpus": 1,
    "command": "python train.py",
    "image": null
  },
  "max_runtime_seconds": 1800
}

The workload also accepts setup (install script), image (container image), memory_gb, region and cloud hints. If GPU capacity is not yet available for your workspace the submission fails closed with 503 gpu_provider_unavailable and no money is held.

CPU_JOB — on-demand CPUs for large simulations

Same reserve-and-bound model, per-minute billing:

{
  "target": "cpu.16vcpu",
  "execution_mode": "NATIVE",
  "workload": {
    "type": "CPU_JOB",
    "kind": "job",
    "resource_type": "cpu",
    "cpus": 16,
    "command": "python big_sim.py"
  },
  "max_runtime_seconds": 3600
}

There is also a free CPU simulation tier (softquantus.sim.cpu, 10 minutes per workspace per month, runtime bound required); past the allowance you get 403 free_cpu_limit_met and can switch to the paid cpu.* tiers.

Idempotency

Send an Idempotency-Key header (any unique string, e.g. a UUID) on every submission:

A fresh authorization returns 201.
Retrying the same key in the same workspace returns the same job with 200 — no double submission, no double reservation.
A key collision that cannot be replayed cleanly returns 409 conflict.

The SDK generates a UUID per run() call automatically (override with idempotency_key=).

Per-run budgets and guardrails

All optional, all applied before money moves (or as a cap at settlement):

Field	Effect
`max_estimated_cost_usd`	Reject before reserving if the estimate exceeds it (`402 max_cost_exceeded`)
`max_shots`	Reject if `shots` exceeds it (`422 max_shots_exceeded`)
`max_actual_charge_usd`	Cap the settled charge. Must be at least the estimate — a lower value is refused (`402 max_charge_below_estimate`)
`max_runtime_seconds`	Bound the runtime. Required for per-minute (GPU/CPU) and per-second (IBM-class QPU) targets — omitting it returns `422 runtime_bound_required`
`max_gpu_minutes`	Additional cap on GPU minutes

For prepaid runs the settled debit can never exceed the reservation, so your balance cannot go negative; the platform absorbs any provider overrun.

Job lifecycle

CREDIT_RESERVED → SUBMITTING → SUBMITTED → PROVIDER_QUEUED → RUNNING → COMPLETED → SETTLED
                                                          ↘ FAILED   ↘ CANCELLED

CREDIT_RESERVED — authorized, worst-case cost held, not yet at the provider. A background pass promotes reserved jobs to the provider (typically within a minute; simulator jobs settle shortly after).
SETTLED — finished; actual_cost_usd is the real charge and the unused reservation is released.
FAILED — no usage charge; the reservation is released.
Reservations stranded without a provider (for example a crash between reserve and submit) are auto-released by a money-safety sweep.

GET /api/v1/platform/execution/jobs/{id} returns the job at any point; GET /api/v1/platform/usage/jobs lists recent runs.

Cancel a job

curl -sS -X POST https://platform.softquantus.com/api/v1/platform/execution/jobs/job_a1b2c3d4/cancel \
  -H "Authorization: Bearer $SQ_API_KEY"

Cancellation asks the provider to abort first:

Not yet dispatched: the job is cancelled immediately and the full reservation is released.
Already at the provider: the job parks in CANCEL_REQUESTED until the abort is confirmed. If shots actually ran before the abort, they are settled and charged; if nothing ran, the reservation is returned in full. You are only ever billed for usage that actually happened.

Next steps

Backends & pricing

Target ids, rates and the cost-safety model.

REST API reference

The full endpoint table and schemas.

Evidence Bundles

Verify how and where a settled run was produced.

Errors

Every refusal reason with status and fix.

Console

Run compute

API & clients

Trust & ecosystem

Run your first workload: a Bell circuit on the SoftQuantus Execution Plane

Quickstart: Bell circuit over REST

Reading the result

The three workload shapes

QUANTUM_CIRCUIT — simulator or real QPU

GPU_JOB — on-demand NVIDIA GPU

CPU_JOB — on-demand CPUs for large simulations

Idempotency

Per-run budgets and guardrails

Job lifecycle

Cancel a job

Next steps

Backends & pricing

REST API reference

Evidence Bundles

Errors

​Quickstart: Bell circuit over REST

​Reading the result

​The three workload shapes

​QUANTUM_CIRCUIT — simulator or real QPU

​GPU_JOB — on-demand NVIDIA GPU

​CPU_JOB — on-demand CPUs for large simulations

​Idempotency

​Per-run budgets and guardrails

​Job lifecycle

​Cancel a job

​Next steps

Backends & pricing

REST API reference

Evidence Bundles

Errors

Quickstart: Bell circuit over REST

Reading the result

The three workload shapes

QUANTUM_CIRCUIT — simulator or real QPU

GPU_JOB — on-demand NVIDIA GPU

CPU_JOB — on-demand CPUs for large simulations

Idempotency

Per-run budgets and guardrails

Job lifecycle

Cancel a job

Next steps