openapi: 3.0.3
info:
contact:
email: support@ionq.co
name: IonQ
url: https://ionq.com/
description: '*Last updated: May 15, 2026*
IonQ''s API for accessing the IonQ Quantum Cloud platform
Please subscribe for automated updates when we perform maintenance or
experience an outage.
In addition, you may use the [status endpoint](#tag/status) to check the
current status of our API.
## Authentication
<SecurityDefinitions />
'
title: IonQ Cloud Platform backends Jobs API
version: v0.4
servers:
- url: https://api.ionq.co/v0.4
tags:
- name: Jobs
paths:
/jobs:
post:
operationId: CreateJob
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreationResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobCreationPayload'
description: 'Submit a single-circuit or multi-circuit job for simulation or execution. In `ionq.multi-circuit.v1` payloads, each entry in `input.circuits` inherits the parent `input.gateset` unless the circuit sets its own `gateset`.
'
x-codeSamples:
- lang: curl
label: Single-circuit QIS job
source: "curl -X POST \"https://api.ionq.co/v0.4/jobs\" \\\n -H \"Authorization: apiKey your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\" : \"ionq.circuit.v1\",\n \"name\": \"Sample circuit\",\n \"metadata\": {\n \"fizz\": \"buzz\",\n \"foo\": \"bar\"\n },\n \"shots\": 500,\n \"backend\": \"qpu.forte-1\",\n \"settings\" :\n {\n \"error_mitigation\":\n {\n \"debiasing\": false\n }\n },\n \"input\": {\n \"qubits\": 2,\n \"gateset\": \"qis\",\n \"circuit\": [\n {\n \"gate\": \"h\",\n \"target\": 0\n }\n ]\n }\n }'\n"
- lang: curl
label: Mixed-gateset multi-circuit job
source: "curl -X POST \"https://api.ionq.co/v0.4/jobs\" \\\n -H \"Authorization: apiKey your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"type\": \"ionq.multi-circuit.v1\",\n \"backend\": \"simulator\",\n \"shots\": 500,\n \"input\": {\n \"gateset\": \"native\",\n \"qubits\": 2,\n \"circuits\": [\n {\n \"name\": \"qis circuit override\",\n \"gateset\": \"qis\",\n \"circuit\": [\n {\n \"gate\": \"h\",\n \"target\": 0\n },\n {\n \"gate\": \"cnot\",\n \"target\": 0,\n \"control\": 1\n }\n ]\n },\n {\n \"name\": \"native circuit from parent\",\n \"circuit\": [\n {\n \"gate\": \"ms\",\n \"targets\": [0, 1],\n \"phases\": [0, 0.25]\n },\n {\n \"gate\": \"gpi2\",\n \"target\": 0,\n \"phase\": 0.75\n }\n ]\n }\n ]\n }\n }'\n"
tags:
- Jobs
get:
operationId: GetJobs
responses:
'200':
description: Successfully retrieved a list of jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/GetJobsResponse'
examples:
Example 1:
value:
jobs:
- id: e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524
status: completed
type: ionq.circuit.v1
backend: simulator
dry_run: false
cost_model: quantum_compute_time
submitter_id: 64b03577072d45001c85e9c4
project_id: 1333d459-cf47-4a5e-acc1-8d4eb4f7b025
parent_job_id: null
session_id: null
metadata: null
name: null
submitted_at: '2025-05-28T20:47:05.440Z'
started_at: null
completed_at: null
predicted_execution_duration_ms: null
predicted_wait_time_ms: null
execution_duration_ms: null
shots: 1000
noise:
model: ideal
failure: null
settings:
compilation: {}
stats:
qubits: 20
circuits: 1
gate_counts:
1q: 1028
2q: 110
predicted_quantum_compute_time_us: 5000
billed_quantum_compute_time_us: 5200
results:
probabilities:
url: /v0.4/jobs/e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524/results/probabilities
output: {}
next: null
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters:
- in: query
name: ids
required: false
schema:
type: array
items:
type: string
- in: query
name: parent_job_id
required: false
schema:
type: string
- in: query
name: status
required: false
schema:
$ref: '#/components/schemas/JobStatus'
- description: Filter jobs by backend target. Supports single target or comma-separated list of targets.
in: query
name: target
required: false
schema:
type: string
example: simulator
- in: query
name: session_id
required: false
schema:
type: string
- description: The id of another user within a shared project to view their submitted jobs. Ignored if not a project member.
in: query
name: submitter_id
required: false
schema:
type: string
- in: query
name: limit
required: false
schema:
format: int32
type: integer
- in: query
name: next
required: false
schema:
type: string
x-codeSamples:
- lang: curl
source: "# Get all jobs:\ncurl \"https://api.ionq.co/v0.4/jobs\" \\\n -H \"Authorization: apiKey your-api-key\"\n"
tags:
- Jobs
delete:
operationId: DeleteJobs
responses:
'200':
description: Successfully deleted a list of jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/JobsDeletedResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobsBulkOperationRequest'
x-codeSamples:
- lang: curl
source: "curl -X DELETE \"https://api.ionq.co/v0.4/jobs\" \\\n -H \"Authorization: apiKey your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"617a1f8b-59d4-435d-aa33-695433d7155e\",\n \"2ccf2773-4c28-468e-a290-2f8554808a25\",\n \"f92df2b6-d212-4f4a-b9ea-024b58c5c3e8\"\n ]\n }'\n"
tags:
- Jobs
/jobs/{UUID}:
get:
operationId: GetJob
responses:
'200':
description: Successfully retrieved a job.
content:
application/json:
schema:
$ref: '#/components/schemas/GetJobResponse'
examples:
Example 1:
value:
id: e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524
status: completed
type: ionq.circuit.v1
backend: simulator
dry_run: false
cost_model: quantum_compute_time
submitter_id: 64b03577072d45001c85e9c4
project_id: 1333d459-cf47-4a5e-acc1-8d4eb4f7b025
parent_job_id: null
child_job_ids: null
session_id: null
metadata: null
name: null
submitted_at: '2025-05-28T20:47:05.440Z'
started_at: null
completed_at: null
predicted_execution_duration_ms: null
predicted_wait_time_ms: null
execution_duration_ms: null
shots: 1000
noise:
model: ideal
failure: null
settings:
compilation: {}
stats:
qubits: 20
circuits: 1
gate_counts:
1q: 1028
2q: 110
predicted_quantum_compute_time_us: 5000
billed_quantum_compute_time_us: 5200
results:
probabilities:
url: /v0.4/jobs/e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524/results/probabilities
output:
compilation: {}
error_mitigation:
debiasing:
variants:
- variant_id: 069ce8f8-f437-7d75-8000-9f5f8c3d7897
qubit_map:
- 4
- 12
- 7
shots: 120
results:
probabilities:
url: /v0.4/jobs/e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524/variants/069ce8f8-f437-7d75-8000-9f5f8c3d7897/results/probabilities
histogram:
url: /v0.4/jobs/e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524/variants/069ce8f8-f437-7d75-8000-9f5f8c3d7897/results/histogram
shots:
url: /v0.4/jobs/e1a09d90-b2ba-4ea5-9fd7-4bfc14eac524/variants/069ce8f8-f437-7d75-8000-9f5f8c3d7897/results/shots
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters:
- description: The UUID of the job — this UUID is provided in the response on job creation.
in: path
name: UUID
required: true
schema:
type: string
x-codeSamples:
- lang: curl
source: "curl \"https://api.ionq.co/v0.4/jobs/617a1f8b-59d4-435d-aa33-695433d7155e\" \\\n -H \"Authorization: apiKey your-api-key\"\n"
tags:
- Jobs
delete:
operationId: DeleteJob
responses:
'200':
description: Successfully deleted a job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobDeletedResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters:
- description: The UUID of the job — this UUID is provided in the response on job creation.
in: path
name: UUID
required: true
schema:
type: string
x-codeSamples:
- lang: curl
source: "curl -X DELETE \"https://api.ionq.co/v0.4/jobs/617a1f8b-59d4-435d-aa33-695433d7155e\" \\\n -H \"Authorization: apiKey your-api-key\"\n"
tags:
- Jobs
/jobs/{UUID}/cost:
get:
operationId: GetJobCost
responses:
'200':
description: Successfully retrieved the cost of a job.
content:
application/json:
schema:
$ref: '#/components/schemas/GetJobCostResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters:
- in: path
name: UUID
required: true
schema:
type: string
x-codeSamples:
- lang: curl
source: "curl \"https://api.ionq.co/v0.4/jobs/0197379a-c3b8-7548-9da4-bbb7067311c1/cost\" \\\n -H \"Authorization: apiKey your-api-key\"\n"
tags:
- Jobs
/jobs/{UUID}/circuits/{lang}:
get:
operationId: GetCompiledFile
responses:
'200':
description: Successfully downloaded a compiled file.
content:
application/json:
schema:
type: string
'403':
description: Forbidden
'404':
description: Not Found
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters:
- in: path
name: UUID
required: true
schema:
type: string
- in: path
name: lang
required: true
schema:
type: string
enum:
- native
- qasm3
tags:
- Jobs
/jobs/{UUID}/status/cancel:
put:
operationId: CancelJob
responses:
'200':
description: Successfully canceled a job.
content:
application/json:
schema:
$ref: '#/components/schemas/JobCanceledResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
description: Cancel the execution of many jobs at once by passing a list of jobs.
summary: Cancel a job
security:
- apiKeyAuth: []
parameters:
- description: The UUID of the job — this UUID is provided in the response on job creation.
in: path
name: UUID
required: true
schema:
type: string
x-codeSamples:
- lang: curl
source: "curl -X PUT \"https://api.ionq.co/v0.4/jobs/617a1f8b-59d4-435d-aa33-695433d7155e/status/cancel\" \\\n -H \"Authorization: apiKey your-api-key\"\n"
tags:
- Jobs
/jobs/status/cancel:
put:
operationId: CancelJobs
responses:
'200':
description: Successfully canceled a list of jobs.
content:
application/json:
schema:
$ref: '#/components/schemas/JobsCanceledResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JobsBulkOperationRequest'
x-codeSamples:
- lang: curl
source: "curl -X PUT \"https://api.ionq.co/v0.4/jobs/status/cancel\" \\\n -H \"Authorization: apiKey your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"ids\": [\n \"617a1f8b-59d4-435d-aa33-695433d7155e\",\n \"2ccf2773-4c28-468e-a290-2f8554808a25\",\n \"f92df2b6-d212-4f4a-b9ea-024b58c5c3e8\"\n ]\n }'\n"
tags:
- Jobs
/jobs/estimate:
get:
operationId: EstimateJobCost
responses:
'200':
description: Successfully retrieved the cost estimate of a job.
content:
application/json:
schema:
$ref: '#/components/schemas/GetJobEstimateResponse'
'429':
description: Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
'500':
description: A generic server failure, please reach out to support@ionq.co for help with this error
'502':
description: Bad Gateway, this can be caused by misbehaving proxies, or by service issues. These can be retried, and downtime can be found on status.ionq.co
'503':
description: Service Unavailable, this is indicative of service outage, please check status.ionq.co
security:
- apiKeyAuth: []
parameters:
- in: query
name: backend
required: true
schema:
$ref: '#/components/schemas/JobBackends'
- in: query
name: type
required: false
schema:
default: ionq.circuit.v1
type: string
- in: query
name: qubits
required: false
schema:
default: 25
format: int32
type: integer
- in: query
name: shots
required: false
schema:
default: 1000
format: int32
type: integer
- in: query
name: 1q_gates
required: false
schema:
default: 0
format: int32
type: integer
- in: query
name: 2q_gates
required: false
schema:
default: 0
format: int32
type: integer
- in: query
name: error_mitigation
required: false
schema:
default: false
type: boolean
tags:
- Jobs
/jobs/{UUID}/results/probabilities:
get:
operationId: GetJobProbabilities
responses:
'200':
description: Probability distribution keyed by decimal qubit state.
content:
application/json:
schema:
$ref: '#/components/schemas/GetResultsResponse'
'404':
description: Job not found or not yet completed.
summary: Fetch the probability distribution for a completed job.
security:
- apiKeyAuth: []
parameters:
- description: The UUID of the job.
in: path
name: UUID
required: true
schema:
type: string
- description: Whether to apply sharpening to the probability distribution.
in: query
name: sharpen
required: false
schema:
type: boolean
tags:
- Jobs
/jobs/{UUID}/variants/{variantId}/results/probabilities:
get:
operationId: GetVariantProbabilities
responses:
'200':
description: Per-variant probabilities histogram
content:
application/json:
schema:
$ref: '#/components/schemas/GetVariantResultsResponse'
'404':
description: Not found
security:
- apiKeyAuth: []
parameters:
- in: path
name: UUID
required: true
schema:
type: string
- in: path
name: variantId
required: true
schema:
type: string
tags:
- Jobs
/jobs/{UUID}/variants/{variantId}/results/histogram:
get:
operationId: GetVariantHistogram
responses:
'200':
description: Per-variant raw histogram (counts)
content:
application/json:
schema:
$ref: '#/components/schemas/GetVariantResultsResponse'
'404':
description: Not found
security:
- apiKeyAuth: []
parameters:
- in: path
name: UUID
required: true
schema:
type: string
- in: path
name: variantId
required: true
schema:
type: string
tags:
- Jobs
/jobs/{UUID}/variants/{variantId}/results/shots:
get:
operationId: GetVariantShots
responses:
'200':
description: Per-variant shot-wise results
content:
application/json:
schema:
$ref: '#/components/schemas/GetVariantResultsResponse'
'404':
description: Not found
security:
- apiKeyAuth: []
parameters:
- in: path
name: UUID
required: true
schema:
type: string
- in: path
name: variantId
required: true
schema:
type: string
tags:
- Jobs
components:
schemas:
CircuitJobCreationPayload:
properties:
name:
type: string
metadata:
$ref: '#/components/schemas/JobMetadata'
description: User defined metadata
shots:
type: integer
format: int32
default: 100
minimum: 1
maximum: 1000000
backend:
$ref: '#/components/schemas/JobBackends'
session_id:
type: string
settings:
properties:
error_mitigation:
properties:
debiasing:
type: boolean
type: object
description: To turn on debiasing, you must request at least 500 shots
compilation:
properties:
opt:
type: number
format: double
precision:
type: string
type: object
type: object
dry_run:
type: boolean
noise:
$ref: '#/components/schemas/Noise'
type:
type: string
enum:
- ionq.circuit.v1
nullable: false
input:
$ref: '#/components/schemas/JsonCircuitInput'
required:
- backend
- type
- input
type: object
additionalProperties: false
GetVariantResultsResponse:
properties: {}
type: object
additionalProperties:
type: number
format: double
JobDeletedResponse:
properties:
id:
type: string
example: 617a1f8b-59d4-435d-aa33-695433d7155e
status:
type: string
enum:
- deleted
nullable: false
required:
- id
- status
type: object
additionalProperties: false
QisGate:
type: string
enum:
- x
- y
- z
- rx
- ry
- rz
- h
- s
- si
- v
- vi
- t
- ti
- not
- cnot
- swap
- xx
- yy
- zz
- pauliexp
GetJobCostResponse:
properties:
dry_run:
type: boolean
example: false
estimated_cost:
properties:
value:
type: number
format: double
example: 24.83
unit:
type: string
example: usd
required:
- value
- unit
type: object
cost:
properties:
value:
type: number
format: double
example: 24.83
unit:
type: string
example: usd
required:
- value
- unit
type: object
required:
- dry_run
- estimated_cost
type: object
additionalProperties: false
JsonObject:
properties: {}
type: object
additionalProperties: {}
CircuitJobCompilationSettings:
properties:
precision:
type: string
opt:
type: number
format: double
gate_basis:
type: string
service_version:
type: string
type: object
additionalProperties: false
GetJobEstimateQueryParams:
properties:
backend:
$ref: '#/components/schemas/JobBackends'
type:
type: string
default: ionq.circuit.v1
qubits:
type: integer
format: int32
default: 25
shots:
type: integer
format: int32
default: 1000
1q_gates:
type: integer
format: int32
default: 0
2q_gates:
type: integer
format: int32
default: 0
error_mitigation:
type: boolean
default: false
required:
- backend
type: object
additionalProperties: false
QuantumFunctionInput:
oneOf:
- $ref: '#/components/schemas/HamiltonianEnergyInput'
- $ref: '#/components/schemas/GenericQuantumFunctionInput'
discriminator:
propertyName: type
mapping:
hamiltonian-energy: '#/components/schemas/HamiltonianEnergyInput'
QuadraticConstraint:
description: "A class to model quadratic inequality constraints of the form\n\n.. math::\n\n x^T P x + r^T x \\leq c."
properties:
quadratic_coeff:
items:
items:
type: number
type: array
title: Quadratic Coeff
type: array
linear_coeff:
items:
type: number
title: Linear Coeff
type: array
rhs:
title: Rhs
type: number
required:
- quadratic_coeff
- linear_coeff
- rhs
type: object
JobStatus:
type: string
enum:
- submitted
- ready
- started
- canceled
- failed
- completed
Registers:
properties: {}
type: object
additionalProperties:
items:
type: number
format: double
nullable: true
type: array
JobBackends:
type: string
description: 'Available options: `simulator`, `qpu.aria-1`, `qpu.aria-2`, `qpu.forte-1`, `qpu.forte-enterprise-1`'
BaseJob:
properties:
id:
type: string
status:
$ref: '#/components/schemas/JobStatus'
type:
type: string
backend:
type: string
dry_run:
type: boolean
submitter_id:
type: string
description: The id of the user who submitted the job
project_id:
type: string
nullable: true
parent_job_id:
type: string
nullable: true
session_id:
type: string
nullable: true
metadata:
allOf:
- $ref: '#/components/schemas/JobMetadata'
nullable: true
name:
type: string
nullable: true
submitted_at:
$ref: '#/components/schemas/IsoTimestamp'
started_at:
allOf:
- $ref: '#/components/schemas/IsoTimestamp'
nullable: true
completed_at:
allOf:
- $ref: '#/components/schemas/IsoTimestamp'
nullable: true
predicted_wait_time_ms:
type: integer
format: int32
nullable: true
predicted_execution_duration_ms:
type: integer
format: int32
nullable: true
execution_duration_ms:
type: integer
format: int32
nullable: true
description: How long the job actually took to run on the QPU. Null if the job hasn't run yet.
shots:
type: integer
format: int32
noise:
$ref: '#/components/schemas/Noise'
description: Only present in the response when `backend` is simulator.
failure:
allOf:
- $ref: '#/components/schemas/Failure'
nullable: true
cost_model:
$ref: '#/components/schemas/CostModel'
description: The billing model used for this job.
output:
$ref: '#/components/schemas/JsonObject'
settings:
$ref: '#/components/schemas/JsonObject'
stats:
$ref: '#/components/schemas/JsonObject'
results:
allOf:
- $ref: '#/components/schemas/JsonObject'
nullable: true
required:
- id
- status
- type
- backend
- dry_run
- submitter_id
- project_id
- parent_job_id
- session_id
- metadata
- name
- submitted_at
- started_at
- completed_at
- predicted_wait_time_ms
- predic
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ionq/refs/heads/main/openapi/ionq-jobs-api-openapi.yml