---
title: "POST /jobs"
method: POST
path: "/jobs"
---

# POST /jobs

`POST /jobs`

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

## Request body

- union
  - CircuitJobCreationPayload
    - `name` string
    - `metadata` JobMetadata
    - `shots` integer — `shots` is ignored by ideal simulator backend.
    - `backend` string, required — Available options: `simulator`, `qpu.aria-1`, `qpu.aria-2`, `qpu.forte-1`, `qpu.forte-enterprise-1`
    - `session_id` string
    - `settings` object
      - `error_mitigation` object — To turn on debiasing, you must request at least 500 shots
        - `symmetry_verification` boolean
        - `debiasing` union
          - object
            - `phi_chi_twirling` object
              - …
          - boolean
      - `compilation` object
        - `service_version` string
        - `gate_basis` string
        - `precision` string
        - `opt` number, double
    - `dry_run` boolean
    - `noise` Noise
      - `model` 'ideal' | 'harmony' | 'harmony-1' | 'harmony-2' | 'aria-1' | 'aria-2' | 'forte-1' | 'forte-enterprise-1', required
      - `seed` integer
    - `type` 'ionq.circuit.v1', required
    - `input` union, required
      - QisCircuitInput
        - `qubits` integer
        - `circuit` GateQisGate[], required
          - `gate` 'x' | 'y' | 'z' | 'rx' | 'ry' | 'rz' | 'h' | 's' | 'si' | 'v' | 'vi' | 't' | 'ti' | 'not' | 'cnot' | 'swap' | 'xx' | 'yy' | 'zz' | 'pauliexp', required
          - `target` integer
          - `targets` number[] — The qubits that a quantum gate is applied to
          - `controls` number[] — The qubits that determine whether the operation is applied to targets.
          - `control` integer
          - `rotation` number, double — Rotation angle for rx/ry/rz gates
        - `gateset` 'qis', required
      - NativeCircuitInput
        - `qubits` integer
        - `circuit` GateNativeGate[], required
          - `gate` 'zz' | 'ms' | 'gpi' | 'gpi2' | 'nop', required
          - `target` integer
          - `targets` number[] — The qubits that a quantum gate is applied to
          - `controls` number[] — The qubits that determine whether the operation is applied to targets.
          - `phase` number, double — Phase for gpi/gpi2 gates
          - `phases` number[] — Phases for ms gate
          - `angle` number, double — Interaction angle for ms gate (in turns, default 0.25)
          - `rotation` number, double — Rotation angle for rx/ry/rz gates
        - `gateset` 'native', required
  - MultiCircuitJobCreationPayload — Submit multiple circuits in a single job. Each circuit inherits the parent `input.gateset` unless overridden by `circuits[].gateset`.
    - `name` string
    - `metadata` JobMetadata
    - `shots` integer — `shots` is ignored by ideal simulator backend.
    - `backend` string, required — Available options: `simulator`, `qpu.aria-1`, `qpu.aria-2`, `qpu.forte-1`, `qpu.forte-enterprise-1`
    - `session_id` string
    - `settings` object
      - `error_mitigation` object — To turn on debiasing, you must request at least 500 shots
        - `symmetry_verification` boolean
        - `debiasing` union
          - object
            - `phi_chi_twirling` object
              - …
          - boolean
      - `compilation` object
        - `service_version` string
        - `gate_basis` string
        - `precision` string
        - `opt` number, double
    - `dry_run` boolean
    - `noise` Noise
      - `model` 'ideal' | 'harmony' | 'harmony-1' | 'harmony-2' | 'aria-1' | 'aria-2' | 'forte-1' | 'forte-enterprise-1', required
      - `seed` integer
    - `type` 'ionq.multi-circuit.v1', required
    - `input` JsonMultiCircuitInput, required
      - `gateset` 'qis' | 'native', required
      - `circuits` union[], required
        - union
          - QISCircuit
            - `name` string
            - `circuit` GateQisGate[], required — Circuit gates. Can be either QIS gates or Native gates depending on the gateset property.
              - …
            - `qubits` integer
            - `registers` Registers
            - `gateset` 'qis' — Optional gateset override for this individual circuit. If not specified, inherits from parent. When set, the circuit must use the appropriate gate format (QIS).
          - NativeCircuit
            - `name` string
            - `circuit` GateNativeGate[], required — Circuit gates. Can be either QIS gates or Native gates depending on the gateset property.
              - …
            - `qubits` integer
            - `registers` Registers
            - `gateset` 'native' — Optional gateset override for this individual circuit. If not specified, inherits from parent. When set, the circuit must use the appropriate gate format (Native).
      - `qubits` integer
  - QuantumFunctionJobCreationPayload
    - `name` string
    - `metadata` JobMetadata
    - `shots` integer
    - `backend` string, required — Available options: `simulator`, `qpu.aria-1`, `qpu.aria-2`, `qpu.forte-1`, `qpu.forte-enterprise-1`
    - `session_id` string
    - `settings` object
      - `error_mitigation` object
        - `debiasing` boolean
    - `dry_run` boolean
    - `type` 'quantum-function', required
    - `input` union, required
      - HamiltonianEnergyInput
        - `data` object, required
          - `type` 'hamiltonian-energy', required
          - `data` HamiltonianEnergyData, required
            - `hamiltonian` HamiltonianPauliTerm[], required
              - …
            - `ansatz` Ansatz, required
              - …
            - `linear_constraints` LinearConstraint[]
              - …
            - `quadratic_constraints` QuadraticConstraint[]
              - …
            - `penalty` number, nullable
            - `cvar_alpha` number, nullable
        - `params` number[]
      - GenericQuantumFunctionInput
        - `type` string, required
        - `data` object, required
        - `params` number[]
  - QctrlQaoaJobCreationPayload — Submit a combinatorial optimization job to solve a maxcut problem using Q-CTRL's QAOA Solver. See our QAOA Job guide for more information.
    - `name` string
    - `metadata` JobMetadata
    - `shots` integer
    - `backend` string, required — Available options: `simulator`, `qpu.aria-1`, `qpu.aria-2`, `qpu.forte-1`, `qpu.forte-enterprise-1`
    - `session_id` string
    - `settings` object
      - `error_mitigation` object
        - `debiasing` boolean
    - `dry_run` boolean
    - `type` 'qctrl.qaoa.v1', required
    - `input` QctrlQaoaJobInput, required
      - `problem_type` 'maxcut', required
      - `problem` object, required — A NetworkX adjacency_graph object
    - `external_settings` object, required
      - `api_credentials` string, required — API Key for your Q-CTRL account
      - `external_organization` string — Optional unique slug for your target Q-CTRL organization

## Response `201`

Created

- JobCreationResponse
  - `id` string, required
  - `status` 'submitted' | 'ready' | 'started' | 'canceled' | 'failed' | 'completed', required
  - `session_id` string, nullable, required

## Other responses

- `429` — Too Many Requests. To get a higher rate limit, please reach out to support@ionq.co
- `500` — A generic server failure, please reach out to support@ionq.co for help with this error
- `502` — 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` — Service Unavailable, this is indicative of service outage, please check status.ionq.co

---

[API](https://skmtc.net/ionq/apis/ionq-cloud-platform-api.md) · [All operations](https://skmtc.net/ionq/apis/ionq-cloud-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ionq/ionq-cloud-platform-api/versions/0410071e1cd0/schema)