Quick start

Four steps from nothing to a completed job. A simulator run costs nothing, so the whole path can be exercised before you spend anything.

1. Create an account and an API key

Sign up, confirm your email address, then create a key in the dashboard. Keys are shown once, at creation. We store only a hash, so we cannot show it to you again.

export APERIS_KEY="apk_…"

2. Store your provider credentials

Aperis submits jobs with your keys, so the hardware runs on your account with IonQ or AWS and bills you directly. Add them in the dashboard under Settings; they are encrypted with a key held in AWS KMS and we keep only a short non-secret fragment so you can tell which is which.

3. Submit a circuit

The circuit format follows the provider, not the device: OpenQASM 3.0 for Amazon Braket, IonQ's own JSON for IonQ direct. The device you name is the device that reaches the payload.

curl -sS https://api.aperis.io/v1/jobs \
  -H "Authorization: Bearer $APERIS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bell state",
    "provider": "ionq",
    "device": "simulator",
    "circuit_definition": "{\"qubits\":2,\"circuit\":[{\"gate\":\"h\",\"target\":0},{\"gate\":\"cnot\",\"control\":0,\"target\":1}]}",
    "shots": 1000
  }'

4. Read the job

One record, the same shape for either provider, carrying the provider's own answer with nothing added. The job id below is an example. Use the one the create call in step 3 returned to you.

curl -sS https://api.aperis.io/v1/jobs/job_01K2C4X9QN7V \
  -H "Authorization: Bearer $APERIS_KEY"

The complete record GET /v1/jobs/{id}

{
  "id": "job_01K2C4X9QN7V",
  "name": "bell state",
  "status": "completed",
  "provider": "ionq",
  "device": "simulator",
  "device_class": "simulator",
  "shots": 1000,
  "circuit_definition": "{\"qubits\":2,\"circuit\":[…]}",
  "result": {
    "probabilities": { "00": 0.5, "11": 0.5 },
    "counts": null,
    "shots": 1000,
    "qubits": 2,
    "precision": "exact",
    "from_simulator": true
  },
  "mitigation": null,
  "error_message": null,
  "provider_job_id": "e9f1…",
  "created_at": "2026-08-06T09:14:02Z",
  "updated_at": "2026-08-06T09:14:39Z",
  "completed_at": "2026-08-06T09:14:39Z",
  "cancel_requested_at": null
}

What the result actually says

A real run, and the two reasons this chart has no error bar. Neither is the one you would guess.

Measurement outcome probabilities for a two-qubit Bell stateTwo outcomes were reported by IonQ's simulator, each with probability 0.5: the state 00 and the state 11. The states 01 and 10 were not returned. The vertical axis runs from 0 to 1.00.51.0|00⟩0.50|01⟩—|10⟩—|11⟩0.50
IonQ simulator, 1000 shots, recorded 6 August 2026. precision is exact, so there is no error bar: the distribution is computed rather than measured and there is no sampling error to bound. counts is null because IonQ returns probabilities, not per-shot results. |01⟩ and |10⟩ were not returned, and a bar of zero would assert a measurement nobody made.

The five job statuses

A job is in one of five states and nothing else. The provider decides which; we map its vocabulary onto ours and keep its own string beside the mapping.

statusset byterminal
queuedus, on submission. It stays here until the provider says otherwiseno
runningthe provider, when the provider reports itno
completedthe provideryes
failedthe provider, or a submission that never reached oneyes
cancelledthe provider, after it confirms. Never on request aloneyes

GET /v1/jobs/{id} → status

Questions the docs do not answer: support@aperis.io.

Create an account