IonQ Sessions API

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 to check the

    current status of our API.


    ## Authentication'
  title: IonQ Cloud Platform Sessions API
  version: v0.4
servers:
- url: https://api.ionq.co/v0.4
tags:
- name: Sessions
paths:
  /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'
      tags:
      - Sessions
      summary: Create session
      x-summary-source: derived
    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
      tags:
      - Sessions
      summary: Get sessions
      x-summary-source: derived
  /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 — this id is provided in the response on session creation.
        in: path
        name: session_id
        required: true
        schema:
          type: string
      tags:
      - Sessions
      summary: End session
      x-summary-source: derived
  /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 — this id is provided in the response on session creation.
        in: path
        name: session_id
        required: true
        schema:
          type: string
      tags:
      - Sessions
      summary: Get session
      x-summary-source: derived
  /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
        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
      tags:
      - Sessions
      summary: Get session jobs
      x-summary-source: derived
components:
  schemas:
    Noise:
      properties:
        model:
          $ref: '#/components/schemas/NoiseModel'
        seed:
          type: integer
          format: int32
      required:
      - model
      type: object
      additionalProperties: false
    Failure:
      properties:
        code:
          type: string
          enum:
          - InvalidInput
          - CompilationError
          - ContractExpiredError
          - DebiasingError
          - InternalError
          - NotEnoughQubits
          - OptimizationError
          - PreflightError
          - QuantumCircuitComplexityError
          - QuantumComputerError
          - QuotaExhaustedError
          - SimulationError
          - SimulationTimeout
          - SystemCancel
          - TooLongPredictedExecutionTime
          - TooManyControls
          - TooManyGates
          - TooManyShots
          - UnknownBillingError
          - UnsupportedGate
        message:
          type: string
      required:
      - code
      - message
      type: object
      additionalProperties: false
    NoiseModel:
      type: string
      enum:
      - ideal
      - harmony
      - harmony-1
      - harmony-2
      - aria-1
      - aria-2
      - forte-1
      - forte-enterprise-1
    CostModel:
      type: string
      enum:
      - quantum_compute_time
      - execution_time
    IsoTimestamp:
      type: string
    SessionsResponse:
      properties:
        organization_id:
          type: string
        sessions:
          items:
            $ref: '#/components/schemas/Session'
          type: array
      required:
      - organization_id
      - sessions
      type: object
      additionalProperties: false
    JsonObject:
      properties: {}
      type: object
      additionalProperties: {}
    CreateSessionRequest:
      properties:
        backend:
          type: string
        settings:
          $ref: '#/components/schemas/SessionSettingsRequest'
      required:
      - backend
      type: object
      additionalProperties: false
    Session:
      properties:
        id:
          type: string
          description: The id of the session.
        created_at:
          type: string
          format: date-time
        organization_id:
          type: string
        backend:
          type:
          - string
          - 'null'
        project_id:
          type:
          - string
          - 'null'
        creator_id:
          type:
          - string
          - 'null'
        ended_at:
          type:
          - string
          - 'null'
          format: date-time
        ender_id:
          type:
          - string
          - 'null'
        settings:
          $ref: '#/components/schemas/SessionSettings'
        active:
          type: boolean
        status:
          $ref: '#/components/schemas/SessionStatusEnum'
        started_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - created_at
      - organization_id
      - backend
      - project_id
      - creator_id
      - ended_at
      - ender_id
      - active
      - status
      - started_at
      type: object
      additionalProperties: false
    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
          - '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/JsonObject'
        stats:
          $ref: '#/components/schemas/JsonObject'
        results:
          allOf:
          - $ref: '#/components/schemas/JsonObject'
      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
      - output
      - settings
      - stats
      - results
      type: object
      additionalProperties: false
    GetJobsResponse:
      properties:
        jobs:
          items:
            $ref: '#/components/schemas/BaseJob'
          type: array
        next:
          type:
          - string
          - 'null'
      required:
      - jobs
      - next
      type: object
      additionalProperties: false
    SessionCostLimit:
      properties:
        unit:
          type: string
        value:
          type: number
          format: double
      required:
      - unit
      - value
      type: object
      additionalProperties: false
    JobMetadata:
      properties: {}
      type: object
      additionalProperties:
        type: string
    SessionStatusEnum:
      enum:
      - created
      - started
      - ended
      type: string
    JobStatus:
      type: string
      enum:
      - submitted
      - ready
      - started
      - canceled
      - failed
      - completed
    SessionSettingsRequest:
      properties:
        job_count_limit:
          type: integer
          format: int32
        duration_limit_min:
          type: integer
          format: int32
        cost_limit:
          $ref: '#/components/schemas/SessionCostLimit'
      type: object
      additionalProperties: false
    SessionSettings:
      properties:
        job_count_limit:
          type: integer
          format: int32
        duration_limit_min:
          type: integer
          format: int32
        cost_limit:
          $ref: '#/components/schemas/SessionCostLimit'
        expires_at:
          type: string
          format: date-time
      type: object
      additionalProperties: false
  securitySchemes:
    apiKeyAuth:
      description: 'API keys are associated with a user and can be created on the [IonQ Quantum Cloud](https://cloud.ionq.com) application. To authenticate, prefix your API Key with `apiKey ` and place it in the `Authorization` request header. Ex: `Authorization: apiKey your-api-key`'
      in: header
      name: Authorization
      type: apiKey