Runs

Submit a run

Validates the circuit, prices it, debits your credits, and executes it. Simulator runs complete inline and come back completed; hardware runs come back queued — poll GET /v1/runs/{id}, subscribe to GET /v1/runs/{id}/stream, or use an SDK's wait helper. A malformed circuit is rejected with 400 before anything is created or charged.

post/v1/runs

Request

  • Base URL: https://api.roroquantum.com
  • URL: https://api.roroquantum.com/v1/runs
  • Auth: HTTP bearer

Request body

machineTargetIdstring required

The target's targetId (codename). targetId below is an accepted alias; send one or the other (both only if they agree).

targetIdstring

Alias for machineTargetId — same meaning, same value.

shotsinteger required

Also bounded by the machine's own minShots..maxShots (see properties).

qasmstring required

OpenQASM 2.0 source for the circuit. A run must carry a circuit: omitting the field is not rejected server-side (the simulators execute a demo Bell circuit and charge for it), which is why every SDK refuses to submit without one.

tagsobject nullable

Optional origin labels for an application submitting on behalf of its own users (opaque ids only, e.g. {"user": "u_42", "job": "nightly"}). Stored for the operator view, never billed on, never used for authorisation, and never echoed back — a run's tags cannot be read from the API. Invalid entries are dropped, not rejected; a label can never fail a paid run.

Example request

{
  "machineTargetId": "roro.sim.sv",
  "targetId": "roro.sim.sv",
  "shots": 5000,
  "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
  "tags": {
    "user": "u_42"
  },
  "resilience": {
    "level": 1,
    "zne": {
      "observable": "ZZ"
    }
  }
}

Response

The created run (already terminal for simulators)

idstring
machineTargetIdstring

The target's codename.

machineNamestring

Friendly display name of the target.

shotsinteger
status'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
costnumber double

Credits charged for this run.

countsobject nullable

Measured bitstring counts (present when completed).

probabilitiesobject nullable

Normalized probabilities per bitstring (present when completed).

errorstring nullable

Failure reason (present when status is failed).

createdAtstring date-time
qasmstring nullable

The submitted OpenQASM 2.0 source.

providerJobIdstring nullable

Upstream provider job id

providerStatusstring nullable

Live raw provider status while running (e.g. 'Running'); null for instant simulator runs.

queuePositioninteger nullable

Jobs ahead on the backend while queued; null for instant simulator runs.

refundableboolean

True when a failed, charged run has a machine-side error — you may POST /v1/runs/{id}/refund.

refundStatus'pending' | 'approved' | 'rejected' nullable

The refund audit trail: null (no refund involved), pending (requested), approved (credited — automatic refunds appear here), rejected.

notebookIdstring nullable

Set when the run was submitted from a console notebook.

labProjectIdstring nullable

Set when the run was submitted from a lab project.

countsProvenance'measured' | 'provider-corrected' nullable

Where counts came from: measured as read out, or provider-corrected (the provider already applied its own readout correction). Null for runs that predate the label — read them as received.

effectiveShotsinteger nullable

Shot-equivalents billed — equal to shots for a plain run.

Example response

{
  "id": "8f3a1c2e-…",
  "machineTargetId": "roro.sim.sv",
  "machineName": "RoRo Statevector Simulator",
  "shots": 5000,
  "status": "completed",
  "cost": 25,
  "counts": {
    "11": 2500,
    "00": 2500
  },
  "probabilities": {
    "11": 0.5,
    "00": 0.5
  },
  "createdAt": "2026-06-05T00:00:00Z",
  "effectiveShots": 5000,
  "resilience": {
    "circuits": 5,
    "effectiveShots": 11264
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.