Running circuits

Queue an OpenQASM 3 circuit to run in a sandboxed container. Four ways in, one execution path out, and every result records how it was produced.

Every result from this plane is recorded as SIMULATION. The worker reaches no quantum hardware, and the class is carried in the result, on the page, and inside the downloaded bundle -- so a file that has left the site still says what produced it.

From the Workbench

Open the Workbench, paste a circuit, and press Queue in the execution plane. You need to be signed in: a job belongs to an account, and its results, audit trail, and cancellation are scoped to you.

Analyze circuit is a different thing. It previews the circuit in the page and is bounded to small circuits. Queueing hands the work to a container with enforced limits and an audit trail, which is what to use for anything whose result you intend to keep or publish.

From the API

Create a token under Settings, then post a job. Repeating an idempotency_key returns the original job rather than running the work twice, so a retried request is safe.

curl -X POST https://ketqat.com/api/execution/jobs \
  -H "authorization: Bearer $KETQAT_TOKEN" \
  -H "content-type: application/json" \
  -d '{
    "idempotency_key": "my-run-1",
    "job": {
      "schema_version": "1.0",
      "parameters": { "operation": "simulate", "qasm": "...", "shots": 1024 }
    }
  }'

The response is 202 with a job id. Poll GET /api/execution/jobs/{id} until the status is terminal, then fetch the bundle. Full schemas are in the OpenAPI document.

From the CLI

export KETQAT_TOKEN=kq_...
ketqat-engine job submit circuit.qasm --registry https://ketqat.com --shots 1024 --wait
ketqat-engine job status <id>  --registry https://ketqat.com
ketqat-engine job bundle <id>  --registry https://ketqat.com

--wait polls until the job finishes and exits non-zero if it did not succeed, so it works in a script without parsing the output. The token is read from the environment and is never accepted as an argument, because arguments appear in shell history and in the process list.

From an MCP client

The SDK exposes submit_execution_job, get_execution_job, and cancel_execution_job.

Submission refuses unless confirmed: true, and the refusal returns what the run would cost: operation, qubit count, shots, execution class, and any conversion loss. Show that to the person and call again only if they agree. A model can call a tool in a loop; a person confirming a specific action cannot be.

What a job can and cannot do

A job names an approved operation and supplies validated parameters. There is no field for a script, a package, an image, or a command, and a request carrying one is refused before it is stored. That absence is the security model -- not a container setting that could be misconfigured, but a shape that cannot express arbitrary execution.

Operations: simulate, transpile, estimate_resources, optimize_zx, check_equivalence, mitigate_zne.

Each job carries a wall-clock timeout, a qubit ceiling, a shot ceiling, and a result-size ceiling. A job that exceeds its time limit is recorded as timed out rather than extended, and an oversized result fails rather than being truncated -- an incomplete scientific result is worse than none.

Cancelling

A queued job is cancelled outright. A job already running is not interrupted: the request is recorded and the job stops at its next transition, so a result may still arrive. The page shows "Cancelling" rather than "Cancelled" while that is true, because reporting it as stopped would be untrue of work that is still running.

Publishing a result

By default a finished job stays a job, with a downloadable bundle. Pass registry_import with a benchmark suite slug to file the result as a run in the registry instead.

That import is refused when the suite requires a metric the operation cannot measure. A simulation produces a measurement histogram, and from a histogram you can derive shots and outcome counts -- you cannot derive a logical error rate. Filling one in would put a scientific claim in the registry that nobody made, so the import fails and names the metrics instead. The job stays succeeded: the work ran, only the filing was declined.

Where your jobs live

Execution jobs lists your own and nothing else. Each job page shows its status, its result, its full audit trail -- submitted, dispatched, claimed, finished -- and a bundle you can download. A job belonging to another account is reported as not found.