openapi: 3.0.3
info:
contact:
email: [email protected]
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 API
version: v0.4
servers:
- url: https://api.ionq.co/v0.4
paths:
/whoami:
get:
description: Retrieves current key associated with this session.
operationId: getWhoami
responses:
'200':
$ref: '#/components/responses/Whoami'
summary: Get current key
tags:
- whoami
x-codeSamples:
- lang: curl
source: "curl \"https://api.ionq.co/v0.4/whoami\" \\\n -H \"Authorization: apiKey your-api-key\"\n"
/backends:
get:
description: This endpoint retrieves all backends.
operationId: getBackends
responses:
'200':
$ref: '#/components/responses/ListBackends'
security: []
summary: Get Backends
tags:
- backends
x-codeSamples:
- lang: curl
source: 'curl "https://api.ionq.co/v0.4/backends"
'
/backends/{backend}:
get:
description: This endpoint retrieves a backend.
operationId: getBackend
parameters:
- $ref: '#/components/parameters/backend'
responses:
'200':
$ref: '#/components/responses/GetBackend'
security: []
summary: Get a Backend
tags:
- backends
x-codeSamples:
- lang: curl
source: 'curl "https://api.ionq.co/v0.4/backends/qpu.aria-1"
'
/backends/{backend}/characterizations:
get:
description: This endpoint retrieves an array of all available backend characterizations, with pagination.
operationId: getCharacterizationsForBackend
parameters:
- $ref: '#/components/parameters/backend'
- description: Characterizations starting at this time (e.g., `start=2025-12-31`)
in: query
name: start
schema:
type: string
- description: Characterizations before this time (e.g., `end=2025-12-31`)
in: query
name: end
schema:
type: string
- description: How many objects to return.
in: query
name: limit
schema:
default: 10
maximum: 10
minimum: 1
type: integer
- $ref: '#/components/parameters/pagination-page'
responses:
'200':
$ref: '#/components/responses/ListCharacterizations'
security: []
summary: Get All Backend Characterizations
tags:
- characterizations
x-codeSamples:
- lang: curl
source: 'curl "https://api.ionq.co/v0.4/backends/qpu.aria-1/characterizations"
'
/backends/{backend}/characterizations/{UUID}:
get:
description: This endpoint retrieves a characterization.
operationId: getCharacterization
parameters:
- $ref: '#/components/parameters/backend'
- $ref: '#/components/parameters/uuid'
responses:
'200':
$ref: '#/components/responses/GetCharacterization'
summary: Get a Characterization
tags:
- characterizations
x-codeSamples:
- lang: curl
source: "curl \"https://api.ionq.co/v0.4/backends/qpu.aria-1/characterizations/aa54e783-0a9b-4f73-ad2f-63983b6aa4a8\"\
\ \\\n -H \"Authorization: apiKey your-api-key\"\n"
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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"
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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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"
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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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"
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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 \u2014 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"
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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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 \u2014 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"
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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"
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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 \u2014 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"
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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"
/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 [email protected]
'500':
description: A generic server failure, please reach out to [email protected] 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
/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
/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
/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
/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
/sessions:
post:
operationId: CreateSession
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
security:
- apiKeyAuth: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
get:
operationId: GetSessions
responses:
'200':
description: Successfully retrieved a list of sessions.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionsResponse'
security:
- apiKeyAuth: []
parameters:
- in: query
name: active
required: false
schema:
type: boolean
/sessions/{session_id}/end:
post:
operationId: EndSession
responses:
'200':
description: Successfully end a session.
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
security:
- apiKeyAuth: []
parameters:
- description: "The id of the session \u2014 this id is provided in the response on session creation."
in: path
name: session_id
required: true
schema:
type: string
/sessions/{session_id}:
get:
operationId: GetSession
responses:
'200':
description: Successfully retrieved a session.
content:
application/json:
schema:
$ref: '#/components/schemas/Session'
security:
- apiKeyAuth: []
parameters:
- description: "The id of the session \u2014 this id is provided in the response on session creation."
in: path
name: session_id
required: true
schema:
type: string
/sessions/{session_id}/jobs:
get:
operationId: GetSessionJobs
responses:
'200':
description: Successfully retrieved a list of jobs from a session.
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
security:
- apiKeyAuth: []
parameters:
- in: path
name: session_id
required: true
schema:
type: string
- 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
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ionq/refs/heads/main/openapi/ionq-quantum-cloud-openapi.yml