> ## Documentation Index > Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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``. - ``shots`` is a TOP-LEVEL field (default 1024). Never put shots inside ``options``: options are forwarded to the backend constructor and an unexpected ``shots`` key fails the job at backend initialization. - 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. Large circuits and full requests: There is no practical size limit on ``circuits_qasm``; circuits of thousands of QASM lines (tens of KB) are normal. Run the exact instance the caller asked for (qubits, steps, shots) -- never silently downscale to a smaller "demo" version. For repeated use of a large circuit, persist it once via ``submit_circuit_for_analytics`` and pass ``circuit_ids``. To confirm a large circuit survived transport, run it on an ideal simulator and compare against a locally computed reference value; verify rather than shrinking the problem. Simulator executions cost $0.00 -- run every requested variant end to end without pausing for a confirmation the user did not ask for. Observable workloads (expectation values): Pass ``observables`` (with ``run_type='Run'``) to measure expectation values instead of sampling bitstrings; ``StatevectorRun`` ignores ``observables``. Over this JSON wire each observable is a ``(pauli_labels, coeffs)`` pair of equal-length lists -- the wire form of a ``SparsePauliOp`` -- nested per circuit, e.g. one observable on one circuit:: "observables": [[ [["ZZ", "XI"], [0.5, -1.0]] ]] Results then carry expectation values in the same nesting (e.g. ``[[-1.8356]]``) instead of count distributions. Parameterized circuits: Submit circuits with parameters UNBOUND as QASM 3.0 in ``circuits_qasm`` (``qiskit.qasm3.dumps``); QASM 2.0 cannot represent unbound parameters. The ``parameters`` / ``observables`` input shapes and the circuits -> observables -> parameters result ordering follow the SDK ``haiqu.run()`` contract (its docstring is the source of truth). 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: ```json options = { "ibm_quantum_token": "", "ibm_quantum_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: ```json options = { "aws_access_key_id": "", "aws_secret_access_key": "", "aws_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: ```json options = { "ionq_api_key": "", } ``` 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. ## OpenAPI ````yaml https://api.haiqu.ai/openapi.json post /ai/run_circuits_on_qpu_or_simulator openapi: 3.1.0 info: title: Haiqu API summary: Haiqu RESTful API service. description: Cloud service providing the access to Haiqu cloud runtime contact: name: Haiqu Inc. url: https://haiqu.ai/ email: info@haiqu.ai version: 1.4.0 servers: [] security: [] paths: /ai/run_circuits_on_qpu_or_simulator: post: summary: Run Circuits On Qpu Or Simulator description: >- 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``. - ``shots`` is a TOP-LEVEL field (default 1024). Never put shots inside ``options``: options are forwarded to the backend constructor and an unexpected ``shots`` key fails the job at backend initialization. - 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. Large circuits and full requests: There is no practical size limit on ``circuits_qasm``; circuits of thousands of QASM lines (tens of KB) are normal. Run the exact instance the caller asked for (qubits, steps, shots) -- never silently downscale to a smaller "demo" version. For repeated use of a large circuit, persist it once via ``submit_circuit_for_analytics`` and pass ``circuit_ids``. To confirm a large circuit survived transport, run it on an ideal simulator and compare against a locally computed reference value; verify rather than shrinking the problem. Simulator executions cost $0.00 -- run every requested variant end to end without pausing for a confirmation the user did not ask for. Observable workloads (expectation values): Pass ``observables`` (with ``run_type='Run'``) to measure expectation values instead of sampling bitstrings; ``StatevectorRun`` ignores ``observables``. Over this JSON wire each observable is a ``(pauli_labels, coeffs)`` pair of equal-length lists -- the wire form of a ``SparsePauliOp`` -- nested per circuit, e.g. one observable on one circuit:: "observables": [[ [["ZZ", "XI"], [0.5, -1.0]] ]] Results then carry expectation values in the same nesting (e.g. ``[[-1.8356]]``) instead of count distributions. Parameterized circuits: Submit circuits with parameters UNBOUND as QASM 3.0 in ``circuits_qasm`` (``qiskit.qasm3.dumps``); QASM 2.0 cannot represent unbound parameters. The ``parameters`` / ``observables`` input shapes and the circuits -> observables -> parameters result ordering follow the SDK ``haiqu.run()`` contract (its docstring is the source of truth). 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: ```json options = { "ibm_quantum_token": "", "ibm_quantum_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: ```json options = { "aws_access_key_id": "", "aws_secret_access_key": "", "aws_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: ```json options = { "ionq_api_key": "", } ``` 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. operationId: run_circuits_on_qpu_or_simulator requestBody: content: application/json: schema: $ref: '#/components/schemas/ContextRunSubmitModel' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ContextRunJobModel' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyQuery: [] - APIKeyHeader: [] components: schemas: ContextRunSubmitModel: properties: experiment_id: type: string title: Experiment Id circuit_ids: anyOf: - items: {} type: array - type: 'null' title: Circuit Ids default: [] parameters: anyOf: - items: {} type: array - type: 'null' title: Parameters description: >- Optional parameter bindings for parameterized circuits. Shape is backend-compatible and typically `[circuit][parameter_set][value]`. shots: type: integer minimum: 1 title: Shots description: Number of measurement shots (must be >= 1) default: 1024 observables: anyOf: - items: items: prefixItems: - items: type: string type: array - items: type: number type: array type: array maxItems: 2 minItems: 2 type: array type: array - type: 'null' title: Observables description: >- Optional observables per circuit, where each observable is `(pauli_strings, coefficients)`; used to compute expectation values instead of bitstring counts. device_id: anyOf: - type: string - type: 'null' title: Device Id default: '' options: anyOf: - additionalProperties: true type: object - type: 'null' title: Options description: >- Backend-specific runtime options. For example: `{'resilience_level': 1, 'optimization_level': 2}`. default: {} use_mitigation: anyOf: - type: boolean - type: 'null' title: Use Mitigation default: false name: anyOf: - type: string - type: 'null' title: Name default: '' description: anyOf: - type: string - type: 'null' title: Description default: '' dry_run: anyOf: - type: boolean - type: 'null' title: Dry Run default: false run_type: type: string enum: - Run - StatevectorRun title: Run Type description: >- Execution mode: `Run` for device/simulator shots, or `StatevectorRun` for exact simulation. default: Run circuits_qasm: anyOf: - items: type: string type: array - type: 'null' title: Circuits Qasm description: >- 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. Circuits with UNBOUND parameters (for a `parameters` sweep) must be QASM 3.0: QASM 2.0 cannot represent unbound parameters. type: object required: - experiment_id title: ContextRunSubmitModel description: >- 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. examples: - circuit_ids: - circ-001 - circ-002 device_id: ibm_fez experiment_id: exp-123 name: Run existing circuits options: optimization_level: 2 resilience_level: 1 run_type: Run shots: 1024 use_mitigation: true - circuits_qasm: - |- OPENQASM 3; qubit[2] q; h q[0]; cx q[0], q[1]; measure q; device_id: aer_simulator experiment_id: exp-123 name: Run QASM circuit run_type: Run shots: 2048 - circuits_qasm: - |- OPENQASM 3; qubit[1] q; rx(0.3) q[0]; experiment_id: exp-123 name: Statevector expectation observables: - - - - Z - - 1 run_type: StatevectorRun ContextRunJobModel: properties: context: type: string title: Context type: object required: - context title: ContextRunJobModel description: |- 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. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError securitySchemes: APIKeyQuery: type: apiKey in: query name: HAIQU_API_KEY APIKeyHeader: type: apiKey in: header name: authorization ````