Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
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:
CircuitJobCompilationSettings:
properties:
precision:
type: string
opt:
type: number
format: double
gate_basis:
type: string
service_version:
type: string
type: object
additionalProperties: false
JobCreationResponse:
properties:
id:
type: string
example: 617a1f8b-59d4-435d-aa33-695433d7155e
status:
$ref: '#/components/schemas/JobStatus'
session_id:
type:
- string
- 'null'
example: null
required:
- id
- status
- session_id
type: object
additionalProperties: false
QctrlQaoaJobInput:
type: object
properties:
problem_type:
type: string
enum:
- maxcut
problem:
type: object
description: A NetworkX adjacency_graph object
example:
directed: false
multigraph: false
graph: []
nodes:
- id: 0
- id: 1
- id: 2
adjacency:
- - id: 1
- id: 2
- - id: 0
- id: 2
- - id: 0
- id: 1
required:
- problem_type
- problem
JobDeletedResponse:
properties:
id:
type: string
example: 617a1f8b-59d4-435d-aa33-695433d7155e
status:
type: string
enum:
- deleted
required:
- id
- status
type: object
additionalProperties: false
CostModel:
type: string
enum:
- quantum_compute_time
- execution_time
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
GetJobEstimateResponse:
properties:
input_values:
$ref: '#/components/schemas/GetJobEstimateQueryParams'
estimated_at:
$ref: '#/components/schemas/IsoTimestamp'
cost_unit:
type: string
rate_information:
properties:
job_cost_minimum:
type: number
format: double
cost_2q_gate:
type: number
format: double
cost_1q_gate:
type: number
format: double
organization:
type: string
required:
- job_cost_minimum
- cost_2q_gate
- cost_1q_gate
- organization
type: object
estimated_cost:
type: number
format: double
estimated_execution_time:
type: number
format: double
current_predicted_queue_time:
type: number
format: double
required:
- input_values
- estimated_at
- cost_unit
- rate_information
- estimated_cost
- estimated_execution_time
- current_predicted_queue_time
type: object
additionalProperties: false
QuantumFunctionInput:
oneOf:
- $ref: '#/components/schemas/HamiltonianEnergyInput'
- $ref: '#/components/schemas/GenericQuantumFunctionInput'
discriminator:
propertyName: type
mapping:
hamiltonian-energy: '#/components/schemas/HamiltonianEnergyInput'
Gate_NativeGate:
properties:
gate:
$ref: '#/components/schemas/NativeGate'
target:
type: integer
format: int32
targets:
items:
type: number
format: double
type: array
description: The qubits that a quantum gate is applied to
controls:
items:
type: number
format: double
type: array
description: The qubits that determine whether the operation is applied to targets.
phase:
type: number
format: double
description: Phase for gpi/gpi2 gates
phases:
items:
type: number
format: double
type: array
description: Phases for ms gate
angle:
type: number
format: double
description: Interaction angle for ms gate (in turns, default 0.25)
rotation:
type: number
format: double
description: Rotation angle for rx/ry/rz gates
required:
- gate
type: object
additionalProperties: false
NativeGate:
type: string
enum:
- zz
- ms
- gpi
- gpi2
- nop
GetCircuitJobResponse:
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
- 'null'
parent_job_id:
type:
- string
- 'null'
session_id:
type:
- string
- 'null'
metadata:
allOf:
- $ref: '#/components/schemas/JobMetadata'
name:
type:
- string
- 'null'
submitted_at:
$ref: '#/components/schemas/IsoTimestamp'
started_at:
allOf:
- $ref: '#/components/schemas/IsoTimestamp'
completed_at:
allOf:
- $ref: '#/components/schemas/IsoTimestamp'
predicted_wait_time_ms:
type:
- integer
- 'null'
format: int32
predicted_execution_duration_ms:
type:
- integer
- 'null'
format: int32
execution_duration_ms:
type:
- integer
- 'null'
format: int32
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'
cost_model:
$ref: '#/components/schemas/CostModel'
description: The billing model used for this job.
output:
$ref: '#/components/schemas/JsonObject'
settings:
$ref: '#/components/schemas/CircuitJobSettings'
stats:
$ref: '#/components/schemas/CircuitJobStats'
results:
allOf:
- $ref: '#/components/schemas/CircuitJobResult'
child_job_ids:
items:
type: string
type:
- array
- 'null'
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
- predicted_execution_duration_ms
- execution_duration_ms
- failure
-
# --- 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