Run Circuits On Qpu Or Simulator

curl --request POST \
  --url 'https://api.example.com/ai/run_circuits_on_qpu_or_simulator?HAIQU_API_KEY=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "experiment_id": "<string>",
  "circuit_ids": [],
  "parameters": [
    "<unknown>"
  ],
  "shots": 1024,
  "observables": [
    [
      [
        [
          "<string>"
        ],
        [
          123
        ]
      ]
    ]
  ],
  "device_id": "",
  "options": {},
  "use_mitigation": false,
  "name": "",
  "description": "",
  "dry_run": false,
  "run_type": "Run",
  "circuits_qasm": [
    "<string>"
  ]
}
'

{
  "context": "<string>"
}

API Reference

Run Circuits On Qpu Or Simulator

Run one or more circuits on a selected QPU or simulator backend.

Use this tool after selecting a device_id from list_qpus_and_simulators and when the caller needs asynchronous execution results for one or more circuits. The request accepts existing circuit_ids or inline circuits_qasm and submits a job; it does not return final quantum results inline.

When to Use:

Call this after list_qpus_and_simulators returns a usable device_id.
Call this when the user wants a run job, not immediate final results.
Call this when circuits already exist as circuit_ids or when inline circuits_qasm should be persisted first.

Constraints:

Provide at least one of circuit_ids or circuits_qasm.
run_type must be exactly Run or StatevectorRun.
The response schema is a lightweight {"context": ...} wrapper rather than a structured run-job object.
Multiple circuits, observables, or parameter sets may yield nested result lists ordered by circuits, then observables, then parameter sets.

Notes:

The job created by this endpoint is visible in the Haiqu Dashboard and Haiqu Lab UI, and execution results are stored in the database as job details.
Provider-specific credentials or runtime options are passed through options when required by the chosen device_id.
This MCP surface currently returns JSON/text payloads only. It does not expose MCP elicitation, sampling, or app-rendered UI.

IBM Quantum devices: Users must obtain an access token from IBM. To run workloads through IBM Cloud, create an API key in IBM Cloud. This token is used as a secure credential to authorize access to quantum processors. Specify the token in the options field when submitting a job to run circuits on IBM Quantum devices, for example:

options = {
    "ibm_quantum_token": "<YOUR_TOKEN>",
    "ibm_quantum_instance": "<YOUR_INSTANCE>",
}

Amazon Braket devices: Users must obtain an access key and secret key from AWS. To run workloads through Amazon Braket, create an IAM user with the appropriate permissions and generate access keys. Specify these keys in the options field when submitting a job to run circuits on Amazon Braket devices, for example:

options = {
    "aws_access_key_id": "<YOUR_ACCESS_KEY_ID>",
    "aws_secret_access_key": "<YOUR_SECRET_KEY>",
    "aws_default_region": "<YOUR_DEFAULT_REGION>",
}

IonQ Cloud devices: Users must obtain an access token from IonQ. To run workloads through IonQ Cloud, create an API key in the IonQ console. This token is used as a secure credential to authorize access to quantum processors. Specify the token in the options field when submitting a job to run circuits on IonQ Cloud devices, for example:

options = {
    "ionq_api_key": "<YOUR_TOKEN>",
}

Args: user: Authenticated user resolved from the API key. data: Run payload. Provide at least one of circuit_ids or circuits_qasm. run_type must be exactly Run or StatevectorRun. db: Active database session.

Returns: A lightweight context wrapper summarizing the submission and next polling step.

Raises: HTTPException: Raised with 400 when neither circuit_ids nor circuits_qasm is provided, 402 when the caller cannot submit billable jobs, or 404 when the experiment is not available to the caller.

POST

run_circuits_on_qpu_or_simulator

Run Circuits On Qpu Or Simulator

curl --request POST \
  --url 'https://api.example.com/ai/run_circuits_on_qpu_or_simulator?HAIQU_API_KEY=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "experiment_id": "<string>",
  "circuit_ids": [],
  "parameters": [
    "<unknown>"
  ],
  "shots": 1024,
  "observables": [
    [
      [
        [
          "<string>"
        ],
        [
          123
        ]
      ]
    ]
  ],
  "device_id": "",
  "options": {},
  "use_mitigation": false,
  "name": "",
  "description": "",
  "dry_run": false,
  "run_type": "Run",
  "circuits_qasm": [
    "<string>"
  ]
}
'

{
  "context": "<string>"
}

Authorizations

HAIQU_API_KEY

string

query

required

Body

application/json

Define run submission payload for MCP execution endpoint.

This model extends :class:haiqu.sdk.schemas.RunSubmitModel with optional inline QASM input so agents can submit and run circuits in one operation.

Attributes: experiment_id: Parent experiment identifier for the run job. circuit_ids: Existing stored circuit IDs to run. Use either this field or circuits_qasm. circuits_qasm: Inline QASM circuits to persist and run in one step. device_id: Backend identifier returned by list_qpus_and_simulators. run_type: Execution mode. Use Run for sampled execution or StatevectorRun for exact simulation. options: Backend-specific runtime options forwarded to the execution provider. parameters: Optional parameter bindings for parameterized circuits. observables: Optional observables used to compute expectation values. use_mitigation: Whether backend mitigation features should be enabled when supported. name: Optional job name. description: Optional plain-text job description. dry_run: Whether to request dry-run cost or planning information instead of a real execution when supported by the backend.

experiment_id

string

required

circuit_ids

any[] | null

parameters

any[] | null

Optional parameter bindings for parameterized circuits. Shape is backend-compatible and typically [circuit][parameter_set][value].

shots

integer

default:1024

Number of measurement shots (must be >= 1)

Required range: x >= 1

observables

tuple[][] | null

Optional observables per circuit, where each observable is (pauli_strings, coefficients); used to compute expectation values instead of bitstring counts.

Show child attributes

device_id

string | null

default:""

options

Options · object

Backend-specific runtime options. For example: {'resilience_level': 1, 'optimization_level': 2}.

use_mitigation

boolean | null

default:false

name

string | null

default:""

description

string | null

default:""

dry_run

boolean | null

default:false

run_type

enum<string>

default:Run

Execution mode: Run for device/simulator shots, or StatevectorRun for exact simulation.

Available options:

Run,

StatevectorRun

circuits_qasm

string[] | null

List of quantum circuits in QASM 2.0 or 3.0 format. Use either this field or circuit_ids field to specify the existing circuits IDs to run.

Response

Successful Response

Represent lightweight run-job context returned by MCP execution tool.

Attributes: context: Submission summary text including the job ID and next polling step. This response model does not expose structured job_id or result fields outside the text payload.

context

string

required

List Qpus And Simulators Compress Circuit With State Compression

⌘I