> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionq.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Submit a quantum circuit to run on a backend.

# Create job

Submit a quantum [circuit](/user-manual/glossary#circuit) to run on a [backend](/user-manual/glossary#backend) by creating a new [job](/user-manual/glossary#job). You can specify the number of [shots](/user-manual/glossary#shots), target backend (QPU or simulator), and optional settings like error mitigation. The job will be queued and executed according to the platform's scheduling system.

Learn more about [submitting circuits via API](/guides/direct-api-submission).


## OpenAPI

````yaml https://api.ionq.co/v0.4/api-docs POST /jobs
openapi: 3.0.3
info:
  contact:
    email: support@ionq.co
    name: IonQ
    url: https://ionq.com/
  description: |
    *Last updated: April 30, 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
security: []
paths:
  /jobs:
    post:
      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`.
      operationId: CreateJob
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreationPayload'
      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: []
      x-codeSamples:
        - lang: curl
          label: Single-circuit QIS job
          source: |
            curl -X POST "https://api.ionq.co/v0.4/jobs" \
              -H "Authorization: apiKey your-api-key" \
              -H "Content-Type: application/json" \
              -d '{
                "type" : "ionq.circuit.v1",
                "name": "Sample circuit",
                "metadata": {
                  "fizz": "buzz",
                  "foo": "bar"
                },
                "shots": 500,
                "backend": "qpu.forte-1",
                "settings" :
                {
                  "error_mitigation":
                  {
                    "debiasing": false
                  }
                },
                "input": {
                  "qubits":  2,
                  "gateset": "qis",
                  "circuit": [
                  {
                    "gate": "h",
                    "target": 0
                  }
                  ]
                }
              }'
        - lang: curl
          label: Mixed-gateset multi-circuit job
          source: |
            curl -X POST "https://api.ionq.co/v0.4/jobs" \
              -H "Authorization: apiKey your-api-key" \
              -H "Content-Type: application/json" \
              -d '{
                "type": "ionq.multi-circuit.v1",
                "backend": "simulator",
                "shots": 500,
                "input": {
                  "gateset": "native",
                  "qubits": 2,
                  "circuits": [
                    {
                      "name": "qis circuit override",
                      "gateset": "qis",
                      "circuit": [
                        {
                          "gate": "h",
                          "target": 0
                        },
                        {
                          "gate": "cnot",
                          "target": 0,
                          "control": 1
                        }
                      ]
                    },
                    {
                      "name": "native circuit from parent",
                      "circuit": [
                        {
                          "gate": "ms",
                          "targets": [0, 1],
                          "phases": [0, 0.25]
                        },
                        {
                          "gate": "gpi2",
                          "target": 0,
                          "phase": 0.75
                        }
                      ]
                    }
                  ]
                }
              }'
components:
  schemas:
    JobCreationPayload:
      anyOf:
        - $ref: '#/components/schemas/CircuitJobCreationPayload'
          title: Single Circuit
        - $ref: '#/components/schemas/MultiCircuitJobCreationPayload'
          title: Multi Circuit
        - $ref: '#/components/schemas/QuantumFunctionJobCreationPayload'
          title: Quantum Function
      example:
        type: ionq.circuit.v1
        input:
          qubits: 1
          gateset: qis
          circuit:
            - gate: h
              target: 0
        backend: qpu.forte-1
        shots: 500
        settings:
          error_mitigation:
            debiasing: false
    JobCreationResponse:
      properties:
        id:
          type: string
          example: 617a1f8b-59d4-435d-aa33-695433d7155e
        status:
          $ref: '#/components/schemas/JobStatus'
        session_id:
          type: string
          nullable: true
          example: null
      required:
        - id
        - status
        - session_id
      type: object
      additionalProperties: false
    CircuitJobCreationPayload:
      properties:
        name:
          type: string
        metadata:
          $ref: '#/components/schemas/JobMetadata'
          description: User defined metadata
        shots:
          type: integer
          format: int32
          default: 100
          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
    MultiCircuitJobCreationPayload:
      properties:
        name:
          type: string
        metadata:
          $ref: '#/components/schemas/JobMetadata'
          description: User defined metadata
        shots:
          type: integer
          format: int32
          default: 100
          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.multi-circuit.v1
          nullable: false
        input:
          $ref: '#/components/schemas/JsonMultiCircuitInput'
          description: >-
            Submit multiple circuits in a single job. Each circuit inherits the
            parent

            `input.gateset` unless overridden by `circuits[].gateset`.
      required:
        - backend
        - type
        - input
      type: object
      additionalProperties: false
      title: JSON Multi Circuit Job
      description: >
        Submit multiple circuits in a single job. Each circuit inherits the
        parent `input.gateset` unless overridden by `circuits[].gateset`.
      example:
        type: ionq.multi-circuit.v1
        backend: simulator
        shots: 500
        input:
          gateset: native
          qubits: 2
          circuits:
            - name: qis circuit override
              gateset: qis
              circuit:
                - gate: h
                  target: 0
                - gate: cnot
                  target: 0
                  control: 1
            - name: native circuit from parent
              circuit:
                - gate: ms
                  targets:
                    - 0
                    - 1
                  phases:
                    - 0
                    - 0.25
                - gate: gpi2
                  target: 0
                  phase: 0.75
    QuantumFunctionJobCreationPayload:
      type: object
      properties:
        name:
          type: string
        metadata:
          $ref: '#/components/schemas/JobMetadata'
        shots:
          type: integer
          format: int32
          default: 100
          maximum: 1000000
        backend:
          $ref: '#/components/schemas/JobBackends'
        session_id:
          type: string
        settings:
          type: object
          properties:
            error_mitigation:
              type: object
              properties:
                debiasing:
                  type: boolean
        dry_run:
          type: boolean
        type:
          type: string
          enum:
            - quantum-function
        input:
          $ref: '#/components/schemas/QuantumFunctionInput'
      required:
        - backend
        - type
        - input
    JobStatus:
      type: string
      enum:
        - submitted
        - ready
        - started
        - canceled
        - failed
        - completed
    JobMetadata:
      properties: {}
      type: object
      additionalProperties:
        type: string
    JobBackends:
      type: string
      description: >-
        Available options: `simulator`, `qpu.aria-1`, `qpu.aria-2`,
        `qpu.forte-1`, `qpu.forte-enterprise-1`
    Noise:
      properties:
        model:
          $ref: '#/components/schemas/NoiseModel'
        seed:
          type: integer
          format: int32
      required:
        - model
      type: object
      additionalProperties: false
    JsonCircuitInput:
      anyOf:
        - $ref: '#/components/schemas/QisCircuitInput'
          title: Qis Circuit
        - $ref: '#/components/schemas/NativeCircuitInput'
          title: Native Circuit
    JsonMultiCircuitInput:
      properties:
        gateset:
          type: string
          enum:
            - qis
            - native
        circuits:
          items:
            anyOf:
              - $ref: '#/components/schemas/QISCircuit'
              - $ref: '#/components/schemas/NativeCircuit'
          type: array
        qubits:
          type: number
          format: double
      required:
        - gateset
        - circuits
      type: object
    QuantumFunctionInput:
      oneOf:
        - $ref: '#/components/schemas/HamiltonianEnergyInput'
        - $ref: '#/components/schemas/GenericQuantumFunctionInput'
      discriminator:
        propertyName: type
        mapping:
          hamiltonian-energy:
            $ref: '#/components/schemas/HamiltonianEnergyInput'
    NoiseModel:
      type: string
      enum:
        - ideal
        - harmony
        - harmony-1
        - harmony-2
        - aria-1
        - aria-2
        - forte-1
        - forte-enterprise-1
    QisCircuitInput:
      properties:
        qubits:
          type: number
          format: double
        circuit:
          items:
            $ref: '#/components/schemas/Gate_QisGate'
          type: array
        gateset:
          type: string
          enum:
            - qis
          nullable: false
      required:
        - circuit
        - gateset
      type: object
      additionalProperties: false
    NativeCircuitInput:
      properties:
        qubits:
          type: number
          format: double
        circuit:
          items:
            $ref: '#/components/schemas/Gate_NativeGate'
          type: array
        gateset:
          type: string
          enum:
            - native
          nullable: false
      required:
        - circuit
        - gateset
      type: object
      additionalProperties: false
    QISCircuit:
      properties:
        name:
          type: string
        circuit:
          items:
            $ref: '#/components/schemas/Gate_QisGate'
          type: array
          description: >-
            Circuit gates. Can be either QIS gates or Native gates depending on
            the gateset property.
        qubits:
          type: integer
          format: int32
        registers:
          $ref: '#/components/schemas/Registers'
          description: >-
            Registers to use in your circuit. Each register is a list of qubit
            indices (starting from zero).
        gateset:
          type: string
          enum:
            - qis
          nullable: false
          description: >-
            Optional gateset override for this individual circuit. If not
            specified, inherits from parent.

            When set, the circuit must use the appropriate gate format (QIS).
      required:
        - circuit
      type: object
      additionalProperties: false
    NativeCircuit:
      properties:
        name:
          type: string
        circuit:
          items:
            $ref: '#/components/schemas/Gate_NativeGate'
          type: array
          description: >-
            Circuit gates. Can be either QIS gates or Native gates depending on
            the gateset property.
        qubits:
          type: integer
          format: int32
        registers:
          $ref: '#/components/schemas/Registers'
          description: >-
            Registers to use in your circuit. Each register is a list of qubit
            indices (starting from zero).
        gateset:
          type: string
          enum:
            - native
          nullable: false
          description: >-
            Optional gateset override for this individual circuit. If not
            specified, inherits from parent.

            When set, the circuit must use the appropriate gate format (Native).
      required:
        - circuit
      type: object
      additionalProperties: false
    HamiltonianEnergyInput:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              type: string
              enum:
                - hamiltonian-energy
            data:
              $ref: '#/components/schemas/HamiltonianEnergyData'
          required:
            - type
            - data
        params:
          items:
            type: number
          type: array
      required:
        - data
    GenericQuantumFunctionInput:
      type: object
      properties:
        type:
          type: string
        data:
          type: object
        params:
          items:
            type: number
          type: array
      required:
        - type
        - data
    Gate_QisGate:
      properties:
        gate:
          $ref: '#/components/schemas/QisGate'
        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.
        control:
          type: integer
          format: int32
        rotation:
          type: number
          format: double
          description: Rotation angle for rx/ry/rz gates
      required:
        - gate
      type: object
      additionalProperties: false
    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
    Registers:
      properties: {}
      type: object
      additionalProperties:
        items:
          type: number
          format: double
          nullable: true
        type: array
    HamiltonianEnergyData:
      properties:
        hamiltonian:
          items:
            $ref: '#/components/schemas/HamiltonianPauliTerm'
          title: Hamiltonian
          type: array
        ansatz:
          $ref: '#/components/schemas/Ansatz'
        linear_constraints:
          default: []
          items:
            $ref: '#/components/schemas/LinearConstraint'
          title: Linear Constraints
          type: array
        quadratic_constraints:
          default: []
          items:
            $ref: '#/components/schemas/QuadraticConstraint'
          title: Quadratic Constraints
          type: array
        penalty:
          default: 0
          nullable: true
          title: Penalty
          type: number
        cvar_alpha:
          default: null
          nullable: true
          title: Cvar Alpha
          type: number
      required:
        - hamiltonian
        - ansatz
      type: object
    QisGate:
      type: string
      enum:
        - x
        - 'y'
        - z
        - rx
        - ry
        - rz
        - h
        - s
        - si
        - v
        - vi
        - t
        - ti
        - not
        - cnot
        - swap
        - xx
        - yy
        - zz
        - pauliexp
    NativeGate:
      type: string
      enum:
        - zz
        - ms
        - gpi
        - gpi2
        - nop
    HamiltonianPauliTerm:
      properties:
        pauli_string:
          title: Pauli String
          type: string
        coefficient:
          title: Coefficient
          type: number
      required:
        - pauli_string
        - coefficient
      type: object
    Ansatz:
      properties:
        data:
          title: Data
          type: string
      required:
        - data
      type: object
    LinearConstraint:
      description: |-
        A class to model linear inequality constraints of the form

        .. math::

            A x \leq b.
      properties:
        coeffs:
          items:
            type: number
          title: Coeffs
          type: array
        rhs:
          title: Rhs
          type: number
      required:
        - coeffs
        - rhs
      type: object
    QuadraticConstraint:
      description: |-
        A class to model quadratic inequality constraints of the form

        .. math::

            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
  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

````