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:
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:
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.
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.
readout_bases: Optional per-qubit Pauli bases to read the circuits out in,
returning one distribution per basis instead of one per circuit.
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.
Optional observables per circuit, where each observable is (pauli_strings, coefficients); used to compute expectation values instead of bitstring counts.
Optional per-qubit Pauli readout bases, Qiskit little-endian, e.g. ['XXXX', 'ZZZZ', 'XZYZ'] (the last character applies to qubit 0). Only X, Y and Z are allowed, one character per qubit, with no duplicate bases; use Z for a qubit that should not be rotated. Returns one bitstring distribution per basis per circuit, nested [circuit][basis][parameter]. Circuits keep their own measurements. Mutually exclusive with observables, and not supported with run_type='StatevectorRun'. Combines with packing: every packed copy is read out in the same basis, so a basis string still has one character per circuit qubit. Each basis is a separate execution, so the cost is len(readout_bases) * shots.
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.
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.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Haiqu","description":"Haiqu is a quantum computing software company building a full-stack quantum intelligence platform for enterprise, research, and developer teams.\n\nHaiqu helps quantum R\u0026D teams move from application ideas to executable prototypes and run frontier quantum workloads on real quantum hardware. The platform combines agentic R\u0026D workflows, Haiqu SDK optimization, and runtime orchestration to improve quantum application development, circuit performance, and execution cost. AI agents: The agent orientation is installed to ``haiqu/sdk/AGENTS.md``, and can also be found at https://github.com/haiqu-ai/haiqu-sdk/blob/main/haiqu/sdk/AGENTS.md","colors":{"primary":"#000000","light":"#CDE9F7","dark":"#092382"},"logo":{"light":"https://mintcdn.com/haiqu/naR3-ajV6yLCfg5I/logo/logo-text-black.svg?fit=max\u0026auto=format\u0026n=naR3-ajV6yLCfg5I\u0026q=85\u0026s=2010ac2de39f76a994323bd9afa6aec1","dark":"https://mintcdn.com/haiqu/naR3-ajV6yLCfg5I/logo/logo-text-white.svg?fit=max\u0026auto=format\u0026n=naR3-ajV6yLCfg5I\u0026q=85\u0026s=826f72d62ee230ca75fe7311455a4012"},"favicon":"https://mintcdn.com/haiqu/QnjSg02a6HjnZweN/logo/logo_black.svg?fit=max\u0026auto=format\u0026n=QnjSg02a6HjnZweN\u0026q=85\u0026s=ff388300b90ced457ceff179ec9ca3a9","navbar":{"links":[{"href":"https://feedback.haiqu.ai","label":"Support"}],"primary":{"type":"button","label":"Request Platform Demo","href":"https://haiqu.ai/contactform"}},"footer":{"socials":{"github":"https://github.com/haiqu-ai","linkedin":"https://linkedin.com/company/haiquai"}},"seo":{"indexing":"all"},"fonts":{"heading":{"family":"SuisseIntlMono","weight":400,"source":"fonts/SuisseIntlMono-Regular-WebS.woff2","format":"woff2"},"body":{"family":"Softcore","weight":400,"source":"fonts/Softcore-Regular.woff2","format":"woff2"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"haiqu","hasAudioNarration":false,"actualSubdomain":"haiqu","customDomains":["docs.haiqu.ai"],"gitSource":{"type":"github","owner":"haiqu-ai","repo":"sdk-docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"liveDeploymentHistoryId":"6adb26c9935ad58d7118117b","collectionId":"093b7692-2a93-43ec-b5d6-290798aa7f23","schemaVersion":"v3","latestBuiltDeploymentHistoryId":"6adb26c9935ad58d7118117b"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6adb26c9935ad58d7118117b","clientVersion":"0.0.3964","searchFilterCounts":[{"language":"default","tag":"API Reference","count":178},{"language":"default","tag":"SDK Reference","count":34},{"language":"default","tag":"Guides","count":31},{"language":"default","tag":"Core features","count":17},{"language":"default","tag":"Data loading","count":9},{"language":"default","tag":"Dashboard","count":8},{"language":"default","tag":"Core platform functions","count":8},{"language":"default","tag":"Circuit Execution","count":5},{"language":"default","tag":"SKQD","count":5},{"language":"default","tag":"Catalog","count":4}]},"assistantConfig":{},"hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"isAtlas":false,"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"@font-face{font-family:\"SkandiaSN\";src:url(/fonts/SkandiaSN-Regular.woff2) format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}@font-face{font-family:\"SkandiaSN\";src:url(/fonts/SkandiaSN-Bold.woff2) format(\"woff2\");font-weight:700;font-style:normal;font-display:swap}@font-face{font-family:\"Softcore\";src:url(/fonts/Softcore-Regular.woff2) format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}@font-face{font-family:\"Softcore\";src:url(/fonts/Softcore-RegularItalic.woff2) format(\"woff2\");font-weight:400;font-style:italic;font-display:swap}@font-face{font-family:\"Softcore\";src:url(/fonts/Softcore-Bold.woff2) format(\"woff2\");font-weight:700;font-style:normal;font-display:swap}@font-face{font-family:\"Softcore\";src:url(/fonts/Softcore-BoldItalic.woff2) format(\"woff2\");font-weight:700;font-style:italic;font-display:swap}@font-face{font-family:\"SuisseIntlMono\";src:url(/fonts/SuisseIntlMono-Regular-WebS.woff2) format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}@font-face{font-family:\"SuisseIntlMono\";src:url(/fonts/SuisseIntlMono-Regular-WebXL.woff2) format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}.code,code,pre{font-family:\"SuisseIntlMono\",monospace}:root{--primary-light:196 213 255;--primary-color:#000000;--light-color:#C4D5FF;--dark-color:#093188;--font-family-suisse-intl-mono:\"SuisseIntlMono\", monospace;--font-family-skandia-sn:\"SkandiaSN\", sans-serif;--font-family-softcore:\"Softcore\", sans-serif}h1,h2,h3,h4,h5,h6{font-family:var(--font-family-suisse-intl-mono)}.case-studies .card-group .card{display:grid;grid-row:span 2;grid-template-rows:subgrid;row-gap:0;padding:1.25rem 1.5rem;border:1px solid rgba(0,0,0,.12);border-radius:1rem}.case-studies .card-group .card:hover{border-color:#000}.case-studies .card-group .card>[data-component-part=card-content-container],.case-studies .card-group .card>[data-component-part=card-content-container]>a,.case-studies .card-group .card>[data-component-part=card-content-container]>a>.w-full{display:contents}"},{"filePath":"styles/content.css","content":".sidebar-group-header{padding-left:0}#sidebar-title,.eyebrow,.sidebar-group>li{text-transform:uppercase;letter-spacing:1px;font-size:12px}.eyebrow,.sidebar-group>li{font-family:var(--font-family-suisse-intl-mono);font-size:10px}.sidebar-group>li>a{padding:9px!important;border-radius:5px!important;line-height:1.5}[data-callout-type=check],[data-callout-type=note],[data-callout-type=tip]{background-color:var(--light-color)!important;border-color:var(--dark-color)!important}[data-callout-type=check] strong,[data-callout-type=check] svg,[data-callout-type=check]>div,[data-callout-type=note] strong,[data-callout-type=note] svg,[data-callout-type=note]>div,[data-callout-type=tip] strong,[data-callout-type=tip] svg,[data-callout-type=tip]>div,[data-component-part=callout-content] h3{color:var(--dark-color)!important}"},{"filePath":"styles/footer.css","content":"#footer{padding:1rem 0}"},{"filePath":"styles/main.css","content":"#navbar~div:has(#content-container){max-width:92rem;padding:0 3rem}#content-container:has([data-page-title=Changelog]){max-width:50rem;margin:0 auto}.changelog-inline-dates .update{flex-direction:column!important;align-items:stretch!important;gap:0!important}.changelog-inline-dates [data-component-part=update-content]>*{min-width:0;overflow-wrap:anywhere}.changelog-inline-dates .update:first-child{padding-top:0}.changelog-inline-dates .update>div,.changelog-inline-dates [data-component-part=update-content]{display:contents}.changelog-inline-dates .update>div:first-child>.absolute,.changelog-inline-dates [data-component-part=update-description]{display:none}.changelog-inline-dates [data-component-part=update-content]>:not(h1,h2,h3,h4){margin-bottom:0!important}.changelog-inline-dates [data-component-part=update-content]>h1{order:-1;margin-bottom:.5rem}.changelog-inline-dates [data-name=frame]{max-width:48rem;margin-inline:auto}.changelog-inline-dates [data-component-part=update-label]{align-self:flex-start;padding:0;background:0 0;font-family:var(--font-family-suisse-intl-mono);font-size:12px;letter-spacing:1px;text-transform:uppercase}#content{margin:32px 0 0}.main-page-title-block h1{font-family:var(--font-family-softcore);font-weight:200;font-size:34px;margin-top:0}.main-page-title-block p{font-family:var(--font-family-softcore);font-weight:400;font-size:15px}.card-group .card{border:0;border-radius:0}.card-group .card>[data-component-part=card-content-container]{padding:1rem 0}.card-group .card>[data-component-part=card-content-container] h2{font-weight:400;margin-bottom:1rem;font-size:14px;letter-spacing:1px}.card-group .card>[data-component-part=card-content-container] [data-component-part=card-content]{font-family:var(--font-family-skandia-sn);font-weight:400;font-size:14px}#quick-navigation{background-color:var(--dark-color);color:#fff;font-size:10px;letter-spacing:1px;border:0;border-radius:5px!important;line-height:1.5;padding:10px;display:inline-block;text-transform:uppercase;font-weight:400}"},{"filePath":"styles/navbar.css","content":"#assistant-entry,#search-bar-entry{text-transform:uppercase;font-family:var(--font-family-suisse-intl-mono);height:32px}#search-bar-entry{background-color:#f1efed;border:0;box-shadow:none;border-radius:6px}#search-bar-entry>div>div,#search-bar-entry>span{font-size:10px;color:var(--primary-color);letter-spacing:1px}#search-bar-entry svg,#topbar-cta-button>a svg{display:none}#assistant-entry{padding:7px 9px}#assistant-entry>span,#topbar-cta-button>a{font-size:10px;line-height:1.5}#assistant-entry,#topbar-cta-button>a{border-radius:5px!important;letter-spacing:1px}#topbar-cta-button>a{border:0;padding:9px}#topbar-cta-button>a>span{border-radius:5px}.nav-tabs>a{font-weight:400;text-shadow:none}#mobile-nav button>span,#navbar button div,#navbar button span,.nav-tabs>a,[role=menu]>a,nav a,nav button{font-family:var(--font-family-suisse-intl-mono);letter-spacing:1px;text-transform:uppercase;font-size:10px}#navbar button div,#navbar button span{font-size:10px!important}"}],"page":{"pagePath":"api-reference/run-circuits-on-qpu-or-simulator","slug":"/api-reference/run-circuits-on-qpu-or-simulator","pageMetadata":{"title":"Run Circuits On Qpu Or Simulator","description":"Run one or more circuits on a selected QPU or simulator backend.\n\nUse this tool after selecting a ``device_id`` from\n``list_qpus_and_simulators`` and when the caller needs asynchronous\nexecution results for one or more circuits. The request accepts existing\n``circuit_ids`` or inline ``circuits_qasm`` and submits a job; it does not\nreturn final quantum results inline.\n\nWhen to Use:\n - Call this after ``list_qpus_and_simulators`` returns a usable\n ``device_id``.\n - Call this when the user wants a run job, not immediate final results.\n - Call this when circuits already exist as ``circuit_ids`` or when\n inline ``circuits_qasm`` should be persisted first.\n\nConstraints:\n - Provide at least one of ``circuit_ids`` or ``circuits_qasm``.\n - ``run_type`` must be exactly ``Run`` or ``StatevectorRun``.\n - ``shots`` is a TOP-LEVEL field (default 1024). Never put shots inside\n ``options``: options are forwarded to the backend constructor and an\n unexpected ``shots`` key fails the job at backend initialization.\n - The response schema is a lightweight ``{\"context\": ...}`` wrapper\n rather than a structured run-job object.\n - Multiple circuits, observables, or parameter sets may yield nested\n result lists ordered by circuits, then observables, then parameter\n sets.\n\nLarge circuits and full requests:\n There is no practical size limit on ``circuits_qasm``; circuits of\n thousands of QASM lines (tens of KB) are normal. Run the exact\n instance the caller asked for (qubits, steps, shots) -- never\n silently downscale to a smaller \"demo\" version. For repeated use of a\n large circuit, persist it once via ``submit_circuit_for_analytics``\n and pass ``circuit_ids``. To confirm a large circuit survived\n transport, run it on an ideal simulator and compare against a locally\n computed reference value; verify rather than shrinking the problem.\n Simulator executions cost $0.00 -- run every requested variant end to\n end without pausing for a confirmation the user did not ask for.\n\nObservable workloads (expectation values):\n Pass ``observables`` (with ``run_type='Run'``) to measure expectation\n values instead of sampling bitstrings; ``StatevectorRun`` ignores\n ``observables``. Over this JSON wire each observable is a\n ``(pauli_labels, coeffs)`` pair of equal-length lists -- the wire form\n of a ``SparsePauliOp`` -- nested per circuit, e.g. one observable on one\n circuit::\n\n \"observables\": [[ [[\"ZZ\", \"XI\"], [0.5, -1.0]] ]]\n\n Results then carry expectation values in the same nesting (e.g.\n ``[[-1.8356]]``) instead of count distributions.\n\nParameterized circuits:\n Submit circuits with parameters UNBOUND as QASM 3.0 in ``circuits_qasm``\n (``qiskit.qasm3.dumps``); QASM 2.0 cannot represent unbound parameters.\n The ``parameters`` / ``observables`` input shapes and the\n circuits -> observables -> parameters result ordering follow the SDK\n ``haiqu.run()`` contract (its docstring is the source of truth).\n\nNotes:\n - The job created by this endpoint is visible in the Haiqu Dashboard\n and Haiqu Lab UI, and execution results are stored in the database as\n job details.\n - Provider-specific credentials or runtime options are passed through\n ``options`` when required by the chosen ``device_id``.\n - This MCP surface currently returns JSON/text payloads only. It does\n not expose MCP elicitation, sampling, or app-rendered UI.\n\nIBM Quantum devices:\n Users must obtain an access token from IBM. To run workloads through\n IBM Cloud, create an API key in IBM Cloud. This token is used as a\n secure credential to authorize access to quantum processors. Specify\n the token in the `options` field when submitting a job to run circuits\n on IBM Quantum devices, for example:\n\n ```json\n options = {\n \"ibm_quantum_token\": \"\u003cYOUR_TOKEN>\",\n \"ibm_quantum_instance\": \"\u003cYOUR_INSTANCE>\",\n }\n ```\n\nAmazon Braket devices:\n Users must obtain an access key and secret key from AWS. To run\n workloads through Amazon Braket, create an IAM user with the\n appropriate permissions and generate access keys. Specify these keys\n in the `options` field when submitting a job to run circuits on Amazon\n Braket devices, for example:\n\n ```json\n options = {\n \"aws_access_key_id\": \"\u003cYOUR_ACCESS_KEY_ID>\",\n \"aws_secret_access_key\": \"\u003cYOUR_SECRET_KEY>\",\n \"aws_default_region\": \"\u003cYOUR_DEFAULT_REGION>\",\n }\n ```\n\nIonQ Cloud devices:\n Users must obtain an access token from IonQ. To run workloads through\n IonQ Cloud, create an API key in the IonQ console. This token is used\n as a secure credential to authorize access to quantum processors.\n Specify the token in the `options` field when submitting a job to run\n circuits on IonQ Cloud devices, for example:\n\n ```json\n options = {\n \"ionq_api_key\": \"\u003cYOUR_TOKEN>\",\n }\n ```\n\nArgs:\n user: Authenticated user resolved from the API key.\n data: Run payload. Provide at least one of ``circuit_ids`` or\n ``circuits_qasm``. ``run_type`` must be exactly ``Run`` or\n ``StatevectorRun``.\n db: Active database session.\n\nReturns:\n A lightweight context wrapper summarizing the submission and next\n polling step.\n\nRaises:\n HTTPException: Raised with ``400`` when neither ``circuit_ids`` nor\n ``circuits_qasm`` is provided, ``402`` when the caller cannot\n submit billable jobs, or ``404`` when the experiment is not\n available to the caller.","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/run_circuits_on_qpu_or_simulator","href":"/api-reference/run-circuits-on-qpu-or-simulator","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n li: \"li\",\n p: \"p\",\n pre: \"pre\",\n span: \"span\",\n ul: \"ul\",\n ..._provideComponents(),\n ...props.components\n }, {CodeBlock} = _components;\n if (!CodeBlock) _missingMdxReference(\"CodeBlock\", true);\n return _jsxs(_Fragment, {\n children: [_jsx(_components.p, {\n children: \"Run one or more circuits on a selected QPU or simulator backend.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Use this tool after selecting a \", _jsx(_components.code, {\n children: \"device_id\"\n }), \" from\\n\", _jsx(_components.code, {\n children: \"list_qpus_and_simulators\"\n }), \" and when the caller needs asynchronous\\nexecution results for one or more circuits. The request accepts existing\\n\", _jsx(_components.code, {\n children: \"circuit_ids\"\n }), \" or inline \", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \" and submits a job; it does not\\nreturn final quantum results inline.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"When to Use:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Call this after \", _jsx(_components.code, {\n children: \"list_qpus_and_simulators\"\n }), \" returns a usable\\n\", _jsx(_components.code, {\n children: \"device_id\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Call this when the user wants a run job, not immediate final results.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Call this when circuits already exist as \", _jsx(_components.code, {\n children: \"circuit_ids\"\n }), \" or when\\ninline \", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \" should be persisted first.\"]\n }), \"\\n\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Constraints:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsxs(_components.li, {\n children: [\"Provide at least one of \", _jsx(_components.code, {\n children: \"circuit_ids\"\n }), \" or \", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"run_type\"\n }), \" must be exactly \", _jsx(_components.code, {\n children: \"Run\"\n }), \" or \", _jsx(_components.code, {\n children: \"StatevectorRun\"\n }), \".\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [_jsx(_components.code, {\n children: \"shots\"\n }), \" is a TOP-LEVEL field (default 1024). Never put shots inside\\n\", _jsx(_components.code, {\n children: \"options\"\n }), \": options are forwarded to the backend constructor and an\\nunexpected \", _jsx(_components.code, {\n children: \"shots\"\n }), \" key fails the job at backend initialization.\"]\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"The response schema is a lightweight \", _jsx(_components.code, {\n children: \"{\\\"context\\\": ...}\"\n }), \" wrapper\\nrather than a structured run-job object.\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"Multiple circuits, observables, or parameter sets may yield nested\\nresult lists ordered by circuits, then observables, then parameter\\nsets.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Large circuits and full requests:\\nThere is no practical size limit on \", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \"; circuits of\\nthousands of QASM lines (tens of KB) are normal. Run the exact\\ninstance the caller asked for (qubits, steps, shots) — never\\nsilently downscale to a smaller “demo” version. For repeated use of a\\nlarge circuit, persist it once via \", _jsx(_components.code, {\n children: \"submit_circuit_for_analytics\"\n }), \"\\nand pass \", _jsx(_components.code, {\n children: \"circuit_ids\"\n }), \". To confirm a large circuit survived\\ntransport, run it on an ideal simulator and compare against a locally\\ncomputed reference value; verify rather than shrinking the problem.\\nSimulator executions cost $0.00 — run every requested variant end to\\nend without pausing for a confirmation the user did not ask for.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Observable workloads (expectation values):\\nPass \", _jsx(_components.code, {\n children: \"observables\"\n }), \" (with \", _jsx(_components.code, {\n children: \"run_type='Run'\"\n }), \") to measure expectation\\nvalues instead of sampling bitstrings; \", _jsx(_components.code, {\n children: \"StatevectorRun\"\n }), \" ignores\\n\", _jsx(_components.code, {\n children: \"observables\"\n }), \". Over this JSON wire each observable is a\\n\", _jsx(_components.code, {\n children: \"(pauli_labels, coeffs)\"\n }), \" pair of equal-length lists — the wire form\\nof a \", _jsx(_components.code, {\n children: \"SparsePauliOp\"\n }), \" — nested per circuit, e.g. one observable on one\\ncircuit::\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"“observables”: [[ [[“ZZ”, “XI”], [0.5, -1.0]] ]]\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Results then carry expectation values in the same nesting (e.g.\\n\", _jsx(_components.code, {\n children: \"[[-1.8356]]\"\n }), \") instead of count distributions.\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Parameterized circuits:\\nSubmit circuits with parameters UNBOUND as QASM 3.0 in \", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \"\\n(\", _jsx(_components.code, {\n children: \"qiskit.qasm3.dumps\"\n }), \"); QASM 2.0 cannot represent unbound parameters.\\nThe \", _jsx(_components.code, {\n children: \"parameters\"\n }), \" / \", _jsx(_components.code, {\n children: \"observables\"\n }), \" input shapes and the\\ncircuits -> observables -> parameters result ordering follow the SDK\\n\", _jsx(_components.code, {\n children: \"haiqu.run()\"\n }), \" contract (its docstring is the source of truth).\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Notes:\"\n }), \"\\n\", _jsxs(_components.ul, {\n children: [\"\\n\", _jsx(_components.li, {\n children: \"The job created by this endpoint is visible in the Haiqu Dashboard\\nand Haiqu Lab UI, and execution results are stored in the database as\\njob details.\"\n }), \"\\n\", _jsxs(_components.li, {\n children: [\"Provider-specific credentials or runtime options are passed through\\n\", _jsx(_components.code, {\n children: \"options\"\n }), \" when required by the chosen \", _jsx(_components.code, {\n children: \"device_id\"\n }), \".\"]\n }), \"\\n\", _jsx(_components.li, {\n children: \"This MCP surface currently returns JSON/text payloads only. It does\\nnot expose MCP elicitation, sampling, or app-rendered UI.\"\n }), \"\\n\"]\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"IBM Quantum devices:\\nUsers must obtain an access token from IBM. To run workloads through\\nIBM Cloud, create an API key in IBM Cloud. This token is used as a\\nsecure credential to authorize access to quantum processors. Specify\\nthe token in the \", _jsx(_components.code, {\n children: \"options\"\n }), \" field when submitting a job to run circuits\\non IBM Quantum devices, for example:\"]\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"4\",\n language: \"json\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"json\",\n children: _jsxs(_components.code, {\n language: \"json\",\n numberOfLines: \"4\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"options = {\"\n })\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"ibm_quantum_token\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"\u003cYOUR_TOKEN>\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"ibm_quantum_instance\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"\u003cYOUR_INSTANCE>\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"}\"\n })\n }), \"\\n\"]\n })\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Amazon Braket devices:\\nUsers must obtain an access key and secret key from AWS. To run\\nworkloads through Amazon Braket, create an IAM user with the\\nappropriate permissions and generate access keys. Specify these keys\\nin the \", _jsx(_components.code, {\n children: \"options\"\n }), \" field when submitting a job to run circuits on Amazon\\nBraket devices, for example:\"]\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"5\",\n language: \"json\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"json\",\n children: _jsxs(_components.code, {\n language: \"json\",\n numberOfLines: \"5\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"options = {\"\n })\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"aws_access_key_id\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"\u003cYOUR_ACCESS_KEY_ID>\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"aws_secret_access_key\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"\u003cYOUR_SECRET_KEY>\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"aws_default_region\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"\u003cYOUR_DEFAULT_REGION>\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"}\"\n })\n }), \"\\n\"]\n })\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"IonQ Cloud devices:\\nUsers must obtain an access token from IonQ. To run workloads through\\nIonQ Cloud, create an API key in the IonQ console. This token is used\\nas a secure credential to authorize access to quantum processors.\\nSpecify the token in the \", _jsx(_components.code, {\n children: \"options\"\n }), \" field when submitting a job to run\\ncircuits on IonQ Cloud devices, for example:\"]\n }), \"\\n\", _jsx(CodeBlock, {\n numberOfLines: \"3\",\n language: \"json\",\n children: _jsx(_components.pre, {\n className: \"shiki shiki-themes github-light-default dark-plus\",\n style: {\n backgroundColor: \"#ffffff\",\n \"--shiki-dark-bg\": \"#0B0C0E\",\n color: \"#1f2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n language: \"json\",\n children: _jsxs(_components.code, {\n language: \"json\",\n numberOfLines: \"3\",\n children: [_jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"options = {\"\n })\n }), \"\\n\", _jsxs(_components.span, {\n className: \"line\",\n children: [_jsx(_components.span, {\n style: {\n color: \"#116329\",\n \"--shiki-dark\": \"#9CDCFE\"\n },\n children: \" \\\"ionq_api_key\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \": \"\n }), _jsx(_components.span, {\n style: {\n color: \"#0A3069\",\n \"--shiki-dark\": \"#CE9178\"\n },\n children: \"\\\"\u003cYOUR_TOKEN>\\\"\"\n }), _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \",\"\n })]\n }), \"\\n\", _jsx(_components.span, {\n className: \"line\",\n children: _jsx(_components.span, {\n style: {\n color: \"#1F2328\",\n \"--shiki-dark\": \"#D4D4D4\"\n },\n children: \"}\"\n })\n }), \"\\n\"]\n })\n })\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Args:\\nuser: Authenticated user resolved from the API key.\\ndata: Run payload. Provide at least one of \", _jsx(_components.code, {\n children: \"circuit_ids\"\n }), \" or\\n\", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \". \", _jsx(_components.code, {\n children: \"run_type\"\n }), \" must be exactly \", _jsx(_components.code, {\n children: \"Run\"\n }), \" or\\n\", _jsx(_components.code, {\n children: \"StatevectorRun\"\n }), \".\\ndb: Active database session.\"]\n }), \"\\n\", _jsx(_components.p, {\n children: \"Returns:\\nA lightweight context wrapper summarizing the submission and next\\npolling step.\"\n }), \"\\n\", _jsxs(_components.p, {\n children: [\"Raises:\\nHTTPException: Raised with \", _jsx(_components.code, {\n children: \"400\"\n }), \" when neither \", _jsx(_components.code, {\n children: \"circuit_ids\"\n }), \" nor\\n\", _jsx(_components.code, {\n children: \"circuits_qasm\"\n }), \" is provided, \", _jsx(_components.code, {\n children: \"402\"\n }), \" when the caller cannot\\nsubmit billable jobs, or \", _jsx(_components.code, {\n children: \"404\"\n }), \" when the experiment is not\\navailable to the caller.\"]\n })]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\nfunction _missingMdxReference(id, component) {\n throw new Error(\"Expected \" + (component ? \"component\" : \"object\") + \" `\" + id + \"` to be defined: you likely forgot to import, pass, or provide it.\");\n}\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Run Circuits On Qpu Or Simulator","description":"Run one or more circuits on a selected QPU or simulator backend.\n\nUse this tool after selecting a ``device_id`` from\n``list_qpus_and_simulators`` and when the caller needs asynchronous\nexecution results for one or more circuits. The request accepts existing\n``circuit_ids`` or inline ``circuits_qasm`` and submits a job; it does not\nreturn final quantum results inline.\n\nWhen to Use:\n - Call this after ``list_qpus_and_simulators`` returns a usable\n ``device_id``.\n - Call this when the user wants a run job, not immediate final results.\n - Call this when circuits already exist as ``circuit_ids`` or when\n inline ``circuits_qasm`` should be persisted first.\n\nConstraints:\n - Provide at least one of ``circuit_ids`` or ``circuits_qasm``.\n - ``run_type`` must be exactly ``Run`` or ``StatevectorRun``.\n - ``shots`` is a TOP-LEVEL field (default 1024). Never put shots inside\n ``options``: options are forwarded to the backend constructor and an\n unexpected ``shots`` key fails the job at backend initialization.\n - The response schema is a lightweight ``{\"context\": ...}`` wrapper\n rather than a structured run-job object.\n - Multiple circuits, observables, or parameter sets may yield nested\n result lists ordered by circuits, then observables, then parameter\n sets.\n\nLarge circuits and full requests:\n There is no practical size limit on ``circuits_qasm``; circuits of\n thousands of QASM lines (tens of KB) are normal. Run the exact\n instance the caller asked for (qubits, steps, shots) -- never\n silently downscale to a smaller \"demo\" version. For repeated use of a\n large circuit, persist it once via ``submit_circuit_for_analytics``\n and pass ``circuit_ids``. To confirm a large circuit survived\n transport, run it on an ideal simulator and compare against a locally\n computed reference value; verify rather than shrinking the problem.\n Simulator executions cost $0.00 -- run every requested variant end to\n end without pausing for a confirmation the user did not ask for.\n\nObservable workloads (expectation values):\n Pass ``observables`` (with ``run_type='Run'``) to measure expectation\n values instead of sampling bitstrings; ``StatevectorRun`` ignores\n ``observables``. Over this JSON wire each observable is a\n ``(pauli_labels, coeffs)`` pair of equal-length lists -- the wire form\n of a ``SparsePauliOp`` -- nested per circuit, e.g. one observable on one\n circuit::\n\n \"observables\": [[ [[\"ZZ\", \"XI\"], [0.5, -1.0]] ]]\n\n Results then carry expectation values in the same nesting (e.g.\n ``[[-1.8356]]``) instead of count distributions.\n\nParameterized circuits:\n Submit circuits with parameters UNBOUND as QASM 3.0 in ``circuits_qasm``\n (``qiskit.qasm3.dumps``); QASM 2.0 cannot represent unbound parameters.\n The ``parameters`` / ``observables`` input shapes and the\n circuits -> observables -> parameters result ordering follow the SDK\n ``haiqu.run()`` contract (its docstring is the source of truth).\n\nNotes:\n - The job created by this endpoint is visible in the Haiqu Dashboard\n and Haiqu Lab UI, and execution results are stored in the database as\n job details.\n - Provider-specific credentials or runtime options are passed through\n ``options`` when required by the chosen ``device_id``.\n - This MCP surface currently returns JSON/text payloads only. It does\n not expose MCP elicitation, sampling, or app-rendered UI.\n\nIBM Quantum devices:\n Users must obtain an access token from IBM. To run workloads through\n IBM Cloud, create an API key in IBM Cloud. This token is used as a\n secure credential to authorize access to quantum processors. Specify\n the token in the `options` field when submitting a job to run circuits\n on IBM Quantum devices, for example:\n\n ```json\n options = {\n \"ibm_quantum_token\": \"\u003cYOUR_TOKEN>\",\n \"ibm_quantum_instance\": \"\u003cYOUR_INSTANCE>\",\n }\n ```\n\nAmazon Braket devices:\n Users must obtain an access key and secret key from AWS. To run\n workloads through Amazon Braket, create an IAM user with the\n appropriate permissions and generate access keys. Specify these keys\n in the `options` field when submitting a job to run circuits on Amazon\n Braket devices, for example:\n\n ```json\n options = {\n \"aws_access_key_id\": \"\u003cYOUR_ACCESS_KEY_ID>\",\n \"aws_secret_access_key\": \"\u003cYOUR_SECRET_KEY>\",\n \"aws_default_region\": \"\u003cYOUR_DEFAULT_REGION>\",\n }\n ```\n\nIonQ Cloud devices:\n Users must obtain an access token from IonQ. To run workloads through\n IonQ Cloud, create an API key in the IonQ console. This token is used\n as a secure credential to authorize access to quantum processors.\n Specify the token in the `options` field when submitting a job to run\n circuits on IonQ Cloud devices, for example:\n\n ```json\n options = {\n \"ionq_api_key\": \"\u003cYOUR_TOKEN>\",\n }\n ```\n\nArgs:\n user: Authenticated user resolved from the API key.\n data: Run payload. Provide at least one of ``circuit_ids`` or\n ``circuits_qasm``. ``run_type`` must be exactly ``Run`` or\n ``StatevectorRun``.\n db: Active database session.\n\nReturns:\n A lightweight context wrapper summarizing the submission and next\n polling step.\n\nRaises:\n HTTPException: Raised with ``400`` when neither ``circuit_ids`` nor\n ``circuits_qasm`` is provided, ``402`` when the caller cannot\n submit billable jobs, or ``404`` when the experiment is not\n available to the caller.","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/run_circuits_on_qpu_or_simulator","href":"/api-reference/run-circuits-on-qpu-or-simulator","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/_mintlify/custom/haiqu/cc26807bbccf8c6c/preload-fonts.js"],"openApiReferenceData":{"operation":{"summary":"Run Circuits On Qpu Or Simulator","description":"Run one or more circuits on a selected QPU or simulator backend.\n\nUse this tool after selecting a ``device_id`` from\n``list_qpus_and_simulators`` and when the caller needs asynchronous\nexecution results for one or more circuits. The request accepts existing\n``circuit_ids`` or inline ``circuits_qasm`` and submits a job; it does not\nreturn final quantum results inline.\n\nWhen to Use:\n - Call this after ``list_qpus_and_simulators`` returns a usable\n ``device_id``.\n - Call this when the user wants a run job, not immediate final results.\n - Call this when circuits already exist as ``circuit_ids`` or when\n inline ``circuits_qasm`` should be persisted first.\n\nConstraints:\n - Provide at least one of ``circuit_ids`` or ``circuits_qasm``.\n - ``run_type`` must be exactly ``Run`` or ``StatevectorRun``.\n - ``shots`` is a TOP-LEVEL field (default 1024). Never put shots inside\n ``options``: options are forwarded to the backend constructor and an\n unexpected ``shots`` key fails the job at backend initialization.\n - The response schema is a lightweight ``{\"context\": ...}`` wrapper\n rather than a structured run-job object.\n - Multiple circuits, observables, or parameter sets may yield nested\n result lists ordered by circuits, then observables, then parameter\n sets.\n\nLarge circuits and full requests:\n There is no practical size limit on ``circuits_qasm``; circuits of\n thousands of QASM lines (tens of KB) are normal. Run the exact\n instance the caller asked for (qubits, steps, shots) -- never\n silently downscale to a smaller \"demo\" version. For repeated use of a\n large circuit, persist it once via ``submit_circuit_for_analytics``\n and pass ``circuit_ids``. To confirm a large circuit survived\n transport, run it on an ideal simulator and compare against a locally\n computed reference value; verify rather than shrinking the problem.\n Simulator executions cost $0.00 -- run every requested variant end to\n end without pausing for a confirmation the user did not ask for.\n\nObservable workloads (expectation values):\n Pass ``observables`` (with ``run_type='Run'``) to measure expectation\n values instead of sampling bitstrings; ``StatevectorRun`` ignores\n ``observables``. Over this JSON wire each observable is a\n ``(pauli_labels, coeffs)`` pair of equal-length lists -- the wire form\n of a ``SparsePauliOp`` -- nested per circuit, e.g. one observable on one\n circuit::\n\n \"observables\": [[ [[\"ZZ\", \"XI\"], [0.5, -1.0]] ]]\n\n Results then carry expectation values in the same nesting (e.g.\n ``[[-1.8356]]``) instead of count distributions.\n\nParameterized circuits:\n Submit circuits with parameters UNBOUND as QASM 3.0 in ``circuits_qasm``\n (``qiskit.qasm3.dumps``); QASM 2.0 cannot represent unbound parameters.\n The ``parameters`` / ``observables`` input shapes and the\n circuits -> observables -> parameters result ordering follow the SDK\n ``haiqu.run()`` contract (its docstring is the source of truth).\n\nNotes:\n - The job created by this endpoint is visible in the Haiqu Dashboard\n and Haiqu Lab UI, and execution results are stored in the database as\n job details.\n - Provider-specific credentials or runtime options are passed through\n ``options`` when required by the chosen ``device_id``.\n - This MCP surface currently returns JSON/text payloads only. It does\n not expose MCP elicitation, sampling, or app-rendered UI.\n\nIBM Quantum devices:\n Users must obtain an access token from IBM. To run workloads through\n IBM Cloud, create an API key in IBM Cloud. This token is used as a\n secure credential to authorize access to quantum processors. Specify\n the token in the `options` field when submitting a job to run circuits\n on IBM Quantum devices, for example:\n\n ```json\n options = {\n \"ibm_quantum_token\": \"\u003cYOUR_TOKEN>\",\n \"ibm_quantum_instance\": \"\u003cYOUR_INSTANCE>\",\n }\n ```\n\nAmazon Braket devices:\n Users must obtain an access key and secret key from AWS. To run\n workloads through Amazon Braket, create an IAM user with the\n appropriate permissions and generate access keys. Specify these keys\n in the `options` field when submitting a job to run circuits on Amazon\n Braket devices, for example:\n\n ```json\n options = {\n \"aws_access_key_id\": \"\u003cYOUR_ACCESS_KEY_ID>\",\n \"aws_secret_access_key\": \"\u003cYOUR_SECRET_KEY>\",\n \"aws_default_region\": \"\u003cYOUR_DEFAULT_REGION>\",\n }\n ```\n\nIonQ Cloud devices:\n Users must obtain an access token from IonQ. To run workloads through\n IonQ Cloud, create an API key in the IonQ console. This token is used\n as a secure credential to authorize access to quantum processors.\n Specify the token in the `options` field when submitting a job to run\n circuits on IonQ Cloud devices, for example:\n\n ```json\n options = {\n \"ionq_api_key\": \"\u003cYOUR_TOKEN>\",\n }\n ```\n\nArgs:\n user: Authenticated user resolved from the API key.\n data: Run payload. Provide at least one of ``circuit_ids`` or\n ``circuits_qasm``. ``run_type`` must be exactly ``Run`` or\n ``StatevectorRun``.\n db: Active database session.\n\nReturns:\n A lightweight context wrapper summarizing the submission and next\n polling step.\n\nRaises:\n HTTPException: Raised with ``400`` when neither ``circuit_ids`` nor\n ``circuits_qasm`` is provided, ``402`` when the caller cannot\n submit billable jobs, or ``404`` when the experiment is not\n available to the caller.","operationId":"run_circuits_on_qpu_or_simulator","requestBody":"1c58cbbc-044c-4b7c-b40a-f992990f31a4","responses":{"200":"749fa6f0-9602-4d7b-a623-5c3a258ec0d9","422":"c9d365c6-ba9f-444a-93b2-5315edba1486"},"security":["9ffe8f7e-3ba6-4368-b205-d23c9a3841fb","3f8904cf-99ba-4bc4-b080-2da19cb8cf5c"],"method":"post","type":"path","servers":[],"path":"/ai/run_circuits_on_qpu_or_simulator","baseUrlOptions":[],"title":"Run Circuits On Qpu Or Simulator","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"content":{"application/json":{"schema":{"properties":{"experiment_id":{"type":"string","title":"Experiment Id","isRequired":true,"uniqueKey":"experiment_id","typeLabel":"string"},"circuit_ids":{"oneOf":[{"type":"array","items":{"oneOf":[{}],"uniqueKey":"circuit_ids.oneOf.0.items.[INDEX]","typeLabel":"any"},"title":"Circuit Ids","default":[],"uniqueKey":"circuit_ids.oneOf.0","typeLabel":"any[]"},{"type":"null","title":"Circuit Ids","default":[],"uniqueKey":"circuit_ids.oneOf.1","typeLabel":"null"}],"uniqueKey":"circuit_ids","typeLabel":"any[] | null"},"parameters":{"oneOf":[{"type":"array","items":{"oneOf":[{}],"uniqueKey":"parameters.oneOf.0.items.[INDEX]","typeLabel":"any"},"title":"Parameters","description":"Optional parameter bindings for parameterized circuits. Shape is backend-compatible and typically `[circuit][parameter_set][value]`.","uniqueKey":"parameters.oneOf.0","typeLabel":"any[]"},{"type":"null","title":"Parameters","description":"Optional parameter bindings for parameterized circuits. Shape is backend-compatible and typically `[circuit][parameter_set][value]`.","uniqueKey":"parameters.oneOf.1","typeLabel":"null"}],"uniqueKey":"parameters","typeLabel":"any[] | null"},"shots":{"type":"integer","minimum":1,"title":"Shots","description":"Number of measurement shots (must be >= 1)","default":1024,"uniqueKey":"shots","typeLabel":"integer"},"observables":{"oneOf":[{"type":"array","items":{"items":{"type":"object","_tupleOriginal":true,"properties":{"[0]":{"items":{"type":"string","uniqueKey":"observables.oneOf.0.items.[INDEX].items.[INDEX].[0].items.[INDEX]","typeLabel":"string"},"type":"array","uniqueKey":"observables.oneOf.0.items.[INDEX].items.[INDEX].[0]","typeLabel":"string[]"},"[1]":{"items":{"type":"number","uniqueKey":"observables.oneOf.0.items.[INDEX].items.[INDEX].[1].items.[INDEX]","typeLabel":"number"},"type":"array","uniqueKey":"observables.oneOf.0.items.[INDEX].items.[INDEX].[1]","typeLabel":"number[]"}},"uniqueKey":"observables.oneOf.0.items.[INDEX].items.[INDEX]","typeLabel":"tuple"},"type":"array","uniqueKey":"observables.oneOf.0.items.[INDEX]","typeLabel":"tuple[]"},"title":"Observables","description":"Optional observables per circuit, where each observable is `(pauli_strings, coefficients)`; used to compute expectation values instead of bitstring counts.","uniqueKey":"observables.oneOf.0","typeLabel":"tuple[][]"},{"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.","uniqueKey":"observables.oneOf.1","typeLabel":"null"}],"uniqueKey":"observables","typeLabel":"tuple[][] | null"},"readout_bases":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"readout_bases.oneOf.0.items.[INDEX]","typeLabel":"string"},"title":"Readout Bases","description":"Optional per-qubit Pauli readout bases, Qiskit little-endian, e.g. `['XXXX', 'ZZZZ', 'XZYZ']` (the last character applies to qubit 0). Only `X`, `Y` and `Z` are allowed, one character per qubit, with no duplicate bases; use `Z` for a qubit that should not be rotated. Returns one bitstring distribution per basis per circuit, nested `[circuit][basis][parameter]`. Circuits keep their own measurements. Mutually exclusive with `observables`, and not supported with `run_type='StatevectorRun'`. Combines with packing: every packed copy is read out in the same basis, so a basis string still has one character per circuit qubit. Each basis is a separate execution, so the cost is `len(readout_bases) * shots`.","uniqueKey":"readout_bases.oneOf.0","typeLabel":"string[]"},{"type":"null","title":"Readout Bases","description":"Optional per-qubit Pauli readout bases, Qiskit little-endian, e.g. `['XXXX', 'ZZZZ', 'XZYZ']` (the last character applies to qubit 0). Only `X`, `Y` and `Z` are allowed, one character per qubit, with no duplicate bases; use `Z` for a qubit that should not be rotated. Returns one bitstring distribution per basis per circuit, nested `[circuit][basis][parameter]`. Circuits keep their own measurements. Mutually exclusive with `observables`, and not supported with `run_type='StatevectorRun'`. Combines with packing: every packed copy is read out in the same basis, so a basis string still has one character per circuit qubit. Each basis is a separate execution, so the cost is `len(readout_bases) * shots`.","uniqueKey":"readout_bases.oneOf.1","typeLabel":"null"}],"uniqueKey":"readout_bases","typeLabel":"string[] | null"},"device_id":{"oneOf":[{"type":"string","title":"Device Id","default":"","uniqueKey":"device_id.oneOf.0","typeLabel":"string"},{"type":"null","title":"Device Id","default":"","uniqueKey":"device_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"device_id","typeLabel":"string | null"},"options":{"oneOf":[{"type":"object","title":"Options","description":"Backend-specific runtime options. For example: `{'resilience_level': 1, 'optimization_level': 2}`.","default":{},"additionalProperties":true,"uniqueKey":"options.oneOf.0","typeLabel":"Options · object"},{"type":"null","title":"Options","description":"Backend-specific runtime options. For example: `{'resilience_level': 1, 'optimization_level': 2}`.","default":{},"uniqueKey":"options.oneOf.1","typeLabel":"null"}],"uniqueKey":"options","typeLabel":"Options · object | null"},"use_mitigation":{"oneOf":[{"type":"boolean","title":"Use Mitigation","default":false,"uniqueKey":"use_mitigation.oneOf.0","typeLabel":"boolean"},{"type":"null","title":"Use Mitigation","default":false,"uniqueKey":"use_mitigation.oneOf.1","typeLabel":"null"}],"uniqueKey":"use_mitigation","typeLabel":"boolean | null"},"name":{"oneOf":[{"type":"string","title":"Name","default":"","uniqueKey":"name.oneOf.0","typeLabel":"string"},{"type":"null","title":"Name","default":"","uniqueKey":"name.oneOf.1","typeLabel":"null"}],"uniqueKey":"name","typeLabel":"string | null"},"description":{"oneOf":[{"type":"string","title":"Description","default":"","uniqueKey":"description.oneOf.0","typeLabel":"string"},{"type":"null","title":"Description","default":"","uniqueKey":"description.oneOf.1","typeLabel":"null"}],"uniqueKey":"description","typeLabel":"string | null"},"dry_run":{"oneOf":[{"type":"boolean","title":"Dry Run","default":false,"uniqueKey":"dry_run.oneOf.0","typeLabel":"boolean"},{"type":"null","title":"Dry Run","default":false,"uniqueKey":"dry_run.oneOf.1","typeLabel":"null"}],"uniqueKey":"dry_run","typeLabel":"boolean | null"},"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","uniqueKey":"run_type","typeLabel":"enum\u003cstring>"},"circuits_qasm":{"oneOf":[{"type":"array","items":{"type":"string","uniqueKey":"circuits_qasm.oneOf.0.items.[INDEX]","typeLabel":"string"},"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.","uniqueKey":"circuits_qasm.oneOf.0","typeLabel":"string[]"},{"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.","uniqueKey":"circuits_qasm.oneOf.1","typeLabel":"null"}],"uniqueKey":"circuits_qasm","typeLabel":"string[] | null"}},"type":"object","required":["experiment_id"],"title":"ContextRunSubmitModel","description":"Define run submission payload for MCP execution endpoint.\n\nThis model extends :class:`haiqu.sdk.schemas.RunSubmitModel` with optional\ninline QASM input so agents can submit and run circuits in one operation.\n\nAttributes:\n experiment_id: Parent experiment identifier for the run job.\n circuit_ids: Existing stored circuit IDs to run. Use either this field\n or ``circuits_qasm``.\n circuits_qasm: Inline QASM circuits to persist and run in one step.\n device_id: Backend identifier returned by ``list_qpus_and_simulators``.\n run_type: Execution mode. Use ``Run`` for sampled execution or\n ``StatevectorRun`` for exact simulation.\n options: Backend-specific runtime options forwarded to the execution\n provider.\n parameters: Optional parameter bindings for parameterized circuits.\n observables: Optional observables used to compute expectation values.\n readout_bases: Optional per-qubit Pauli bases to read the circuits out in,\n returning one distribution per basis instead of one per circuit.\n use_mitigation: Whether backend mitigation features should be enabled\n when supported.\n name: Optional job name.\n description: Optional plain-text job description.\n dry_run: Whether to request dry-run cost or planning information instead\n 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;\nqubit[2] q;\nh q[0];\ncx q[0], q[1];\nmeasure q;"],"device_id":"aer_simulator","experiment_id":"exp-123","name":"Run QASM circuit","run_type":"Run","shots":2048},{"circuits_qasm":["OPENQASM 3;\ninclude \"stdgates.inc\";\nqubit[2] q;\nbit[2] c;\nh q[0];\ncx q[0], q[1];\nc = measure q;"],"device_id":"aer_simulator","experiment_id":"exp-123","name":"Bell state in two readout bases","readout_bases":["ZZ","XX"],"run_type":"Run","shots":4096},{"circuits_qasm":["OPENQASM 3;\nqubit[1] q;\nrx(0.3) q[0];"],"experiment_id":"exp-123","name":"Statevector expectation","observables":[[[["Z"],[1]]]],"run_type":"StatevectorRun"}],"uniqueKey":"","typeLabel":"ContextRunSubmitModel · object"},"examples":{"Example":{"title":"Example","value":{"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}}},"exampleType":"generated"}},"required":true,"exampleType":"generated"},"responses":{"749fa6f0-9602-4d7b-a623-5c3a258ec0d9":{"description":"Successful Response","content":{"application/json":{"schema":{"properties":{"context":{"type":"string","title":"Context","isRequired":true,"uniqueKey":"context","typeLabel":"string"}},"type":"object","required":["context"],"title":"ContextRunJobModel","description":"Represent lightweight run-job context returned by MCP execution tool.\n\nAttributes:\n context: Submission summary text including the job ID and next polling\n step. This response model does not expose structured ``job_id`` or\n result fields outside the text payload.","uniqueKey":"","typeLabel":"ContextRunJobModel · object"},"examples":{"Example":{"title":"Example","value":{"context":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"c9d365c6-ba9f-444a-93b2-5315edba1486":{"description":"Validation Error","content":{"application/json":{"schema":{"properties":{"detail":{"items":{"properties":{"loc":{"items":{"oneOf":[{"type":"string","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.0","typeLabel":"string"},{"type":"integer","uniqueKey":"detail.items.[INDEX].loc.items.[INDEX].oneOf.1","typeLabel":"integer"}],"uniqueKey":"detail.items.[INDEX].loc.items.[INDEX]","typeLabel":"string | integer"},"type":"array","title":"Location","isRequired":true,"uniqueKey":"detail.items.[INDEX].loc","typeLabel":"(string | integer)[]"},"msg":{"type":"string","title":"Message","isRequired":true,"uniqueKey":"detail.items.[INDEX].msg","typeLabel":"string"},"type":{"type":"string","title":"Error Type","isRequired":true,"uniqueKey":"detail.items.[INDEX].type","typeLabel":"string"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError","uniqueKey":"detail.items.[INDEX]","typeLabel":"ValidationError · object"},"type":"array","title":"Detail","uniqueKey":"detail","typeLabel":"ValidationError · object[]"}},"type":"object","title":"HTTPValidationError","uniqueKey":"","typeLabel":"HTTPValidationError · object"},"examples":{"Example":{"title":"Example","value":{"detail":[{"loc":["\u003cstring>"],"msg":"\u003cstring>","type":"\u003cstring>"}]}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"9ffe8f7e-3ba6-4368-b205-d23c9a3841fb":{"APIKeyQuery":{"type":"apiKey","in":"query","name":"HAIQU_API_KEY","scopes":[],"schemeName":"APIKeyQuery"}},"3f8904cf-99ba-4bc4-b080-2da19cb8cf5c":{"APIKeyHeader":{"type":"apiKey","in":"header","name":"authorization","scopes":[],"schemeName":"APIKeyHeader"}}},"servers":{},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"query","name":"HAIQU_API_KEY","scopes":[],"schemeName":"APIKeyQuery"},"schema":{"title":"HAIQU_API_KEY","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"APIKeyQuery","name":"HAIQU_API_KEY"}],"title":"APIKeyQuery"},{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"authorization","scopes":[],"schemeName":"APIKeyHeader"},"schema":{"title":"authorization","type":"string","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"APIKeyHeader","name":"authorization"}],"title":"APIKeyHeader"}]},"originalFileLocation":"https://api.haiqu.ai/openapi.json"},"subdomain":"haiqu","siteName":"Haiqu","title":"Run Circuits On Qpu Or Simulator - Haiqu","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-23T09:20:14.358Z","originalFileLocation":"api-reference/run-circuits-on-qpu-or-simulator.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"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 {\u0026quot;context\u0026quot;: ...} 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 \u0026quot;demo\u0026quot; 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=\u0026#x27;Run\u0026#x27;) 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:: \u0026quot;observables\u0026quot;: [[ [[\u0026quot;ZZ\u0026quot;, \u0026quot;XI\u0026quot;], [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 -\u0026gt; observables -\u0026gt; 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 = { \u0026quot;ibm_quantum_token\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;ibm_quantum_instance\u0026quot;: \u0026quot;\u0026quot;, } 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 = { \u0026quot;aws_access_key_id\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;aws_secret_access_key\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;aws_default_region\u0026quot;: \u0026quot;\u0026quot;, } 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 = { \u0026quot;ionq_api_key\u0026quot;: \u0026quot;\u0026quot;, } 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.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Haiqu\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Run Circuits On Qpu Or Simulator - Haiqu\">\u003cmeta data-mint-head property=\"og:description\" content=\"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 {\u0026quot;context\u0026quot;: ...} 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 \u0026quot;demo\u0026quot; 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=\u0026#x27;Run\u0026#x27;) 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:: \u0026quot;observables\u0026quot;: [[ [[\u0026quot;ZZ\u0026quot;, \u0026quot;XI\u0026quot;], [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 -\u0026gt; observables -\u0026gt; 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 = { \u0026quot;ibm_quantum_token\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;ibm_quantum_instance\u0026quot;: \u0026quot;\u0026quot;, } 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 = { \u0026quot;aws_access_key_id\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;aws_secret_access_key\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;aws_default_region\u0026quot;: \u0026quot;\u0026quot;, } 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 = { \u0026quot;ionq_api_key\u0026quot;: \u0026quot;\u0026quot;, } 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.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Haiqu\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://haiqu.mintlify.app/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Run+Circuits+On+Qpu+Or+Simulator\u0026amp;description=Run+one+or+more+circuits+on+a+selected+QPU+or+simulator+backend.%0A%0AUse+this+tool+after+selecting+a+%60%60device_id%60%60+from%0A%60%60list_qpus_and_simulators%60%60+and+when+the+c\u0026amp;theme=a89afdb9c3ab85c54450697e\u0026amp;signature=cac55f33a6a8565ae65ff1951c23cde154b76caa8d20c4643c4af59c76bb8ac1\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Run Circuits On Qpu Or Simulator - Haiqu\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"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 {\u0026quot;context\u0026quot;: ...} 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 \u0026quot;demo\u0026quot; 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=\u0026#x27;Run\u0026#x27;) 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:: \u0026quot;observables\u0026quot;: [[ [[\u0026quot;ZZ\u0026quot;, \u0026quot;XI\u0026quot;], [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 -\u0026gt; observables -\u0026gt; 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 = { \u0026quot;ibm_quantum_token\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;ibm_quantum_instance\u0026quot;: \u0026quot;\u0026quot;, } 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 = { \u0026quot;aws_access_key_id\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;aws_secret_access_key\u0026quot;: \u0026quot;\u0026quot;, \u0026quot;aws_default_region\u0026quot;: \u0026quot;\u0026quot;, } 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 = { \u0026quot;ionq_api_key\u0026quot;: \u0026quot;\u0026quot;, } 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.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://haiqu.mintlify.app/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Run+Circuits+On+Qpu+Or+Simulator\u0026amp;description=Run+one+or+more+circuits+on+a+selected+QPU+or+simulator+backend.%0A%0AUse+this+tool+after+selecting+a+%60%60device_id%60%60+from%0A%60%60list_qpus_and_simulators%60%60+and+when+the+c\u0026amp;theme=a89afdb9c3ab85c54450697e\u0026amp;signature=cac55f33a6a8565ae65ff1951c23cde154b76caa8d20c4643c4af59c76bb8ac1\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/haiqu/oEFiEtbJmeciuADt/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Haiqu\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#000000\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/run-circuits-on-qpu-or-simulator.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.haiqu.ai/#organization\",\"name\":\"Haiqu\",\"url\":\"https://docs.haiqu.ai\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/haiqu/naR3-ajV6yLCfg5I/logo/logo-text-black.svg?fit=max\u0026auto=format\u0026n=naR3-ajV6yLCfg5I\u0026q=85\u0026s=2010ac2de39f76a994323bd9afa6aec1\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.haiqu.ai#website\",\"name\":\"Haiqu\",\"url\":\"https://docs.haiqu.ai\",\"publisher\":{\"@id\":\"https://docs.haiqu.ai/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator#webpage\",\"url\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator\",\"name\":\"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.\",\"dateModified\":\"2026-10-23T09:20:14.358Z\",\"isPartOf\":{\"@id\":\"https://docs.haiqu.ai#website\"},\"breadcrumb\":{\"@id\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"API Reference\",\"item\":\"https://docs.haiqu.ai/api-reference/submit-circuit\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Run Circuits On Qpu Or Simulator\",\"item\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator#apireference\",\"headline\":\"Run Circuits On Qpu Or Simulator\",\"name\":\"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.\",\"url\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator\",\"mainEntityOfPage\":{\"@id\":\"https://docs.haiqu.ai/api-reference/run-circuits-on-qpu-or-simulator#webpage\"},\"dateModified\":\"2026-10-23T09:20:14.358Z\",\"publisher\":{\"@id\":\"https://docs.haiqu.ai/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.haiqu.ai#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Haiqu\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Haiqu","nav":{"global":null,"tabs":[{"tab":"Welcome","pages":[{"title":"Welcome","href":""}]},{"tab":"Haiqu AgenticOS","pages":[{"title":"Haiqu AgenticOS","href":"/agentic-os"}]},{"tab":"Guides","versions":[{"version":"1.7.0","groups":[{"group":"Quick Start","pages":[{"title":"Get Started","href":"/quickstart/qs_intro"},{"title":"Local Installation","href":"/quickstart/qs_local"},{"title":"Update the SDK","href":"/quickstart/update-the-sdk"},{"title":"AI Assisted Development","href":"/quickstart/ai-assisted-development"}]},{"group":"Core features","pages":[{"title":"SDK Overview","href":"/core_features/overview"},{"title":"Dashboard Overview","href":"/dashboard-overview"},{"title":"Distribution Loading","href":"/core_features/data_loading_dist"},{"title":"Data Loading","href":"/core_features/data_loading_vect"},{"title":"Feature embedding","href":"/core_features/data_loading_isom"},{"title":"Compression","href":"/core_features/compression"},{"title":"Working with Haiqu Circuits","href":"/core_features/haiqu_circuits"},{"title":"Transpilation","href":"/core_features/transpilation"},{"title":"Measuring in different bases","href":"/core_features/readout_bases"},{"title":"Error Mitigation","href":"/core_features/error_shield"},{"title":"Variational algorithms","href":"/core_features/qml"},{"title":"SU(2)-equivariant gates","href":"/core_features/equivariant_gates"},{"title":"Optimization \u0026 Postprocessing","href":"/core_features/postprocessing"},{"title":"Experiment Tracking","href":"/core_features/exp_tracking"},{"title":"Experiment Sharing","href":"/core_features/experiment-sharing"},{"title":"Circuit Analytics","href":"/core_features/circ_analytics"},{"title":"Job Performance Metrics","href":"/core_features/quality"}]},{"group":"Hybrid programs","pages":[{"title":"Overview","href":"/hybrid/overview"},{"title":"Building and running flows","href":"/hybrid/flows"}]},{"group":"Integrations","pages":[{"title":"IBM Quantum","href":"/integrations/ibm"},{"title":"Amazon Braket","href":"/integrations/amazon"},{"title":"IonQ Cloud","href":"/integrations/ionq"},{"title":"IQM Resonance","href":"/integrations/iqm"}]},{"group":"Catalog","pages":[{"title":"QML building blocks","href":"/catalog/qml_building_blocks"},{"title":"Benchmarks data sheet","href":"/catalog/datasheet"},{"title":"Characteristic Functions","href":"/catalog/characteristic_functions"},{"title":"Multivariate Probability Distributions","href":"/catalog/multivariate_distributions"}]}]}]},{"tab":"Dashboard","pages":[{"title":"Dashboard","href":"/dashboard/overview"}]},{"tab":"SDK Reference","versions":[{"version":"1.7.0","groups":[{"group":"Core platform functions","pages":[{"title":"Login","href":"/reference/core/login"},{"title":"Init or Update Experiment","href":"/reference/core/init"},{"title":"Log Objects","href":"/reference/core/log"},{"title":"List Objects","href":"/reference/core/list"},{"title":"Get Objects","href":"/reference/core/get"},{"title":"Draw","href":"/reference/core/draw"},{"title":"Credentials Helpers","href":"/reference/core/credentials_helpers"},{"title":"Health Check","href":"/reference/core/health_check"}]},{"group":"Data loading","pages":[{"title":"Distribution Loading","href":"/reference/data/distribution"},{"title":"Multivariate Distribution Loading","href":"/reference/data/multivariate_distribution"},{"title":"Vector Loading","href":"/reference/data/vector"},{"title":"Block-wise Vector Loading","href":"/reference/data/block_vector"},{"title":"Entangled Manifold Embedding","href":"/reference/data/entangled_manifold_embedding"},{"title":"MPS Loading","href":"/reference/data/mps_loading"},{"title":"Function Loading","href":"/reference/data/function"},{"title":"Fourier Loading","href":"/reference/data/fourier"},{"title":"Circuit Synthesis Options","href":"/reference/data/synthesis_options"}]},{"group":"Middleware","pages":[{"title":"State Compression","href":"/reference/middleware/compression"},{"title":"Observable Backpropagation","href":"/reference/middleware/observable-backpropagation"}]},{"group":"Circuit Execution","pages":[{"title":"Flow","href":"/reference/run/flow"},{"title":"Hybrid Program","href":"/reference/run/hybrid_program"},{"title":"Run","href":"/reference/run/run"},{"title":"Statevector Run","href":"/reference/run/statevector_run"},{"title":"Transpile","href":"/reference/run/transpile"}]},{"group":"Optimization","pages":[{"title":"Problem Formulations","href":"/reference/optimization/problem"},{"title":"Postprocessing","href":"/reference/optimization/postprocessing"}]},{"group":"Variational Algorithms","pages":[{"title":"Variational Quantum Optimization","href":"/reference/qml/variational"},{"title":"SU(2)-equivariant gates","href":"/reference/qml/equivariant"},{"title":"Pretrain","href":"/reference/qml/pretrain"}]},{"group":"SKQD","pages":[{"title":"Postprocessing","href":"/reference/skqd/postprocess_skqd"},{"title":"Configuration recovery","href":"/reference/skqd/configuration_recovery"},{"title":"Hubbard Model","href":"/reference/skqd/hubbard"},{"title":"SIAM Model","href":"/reference/skqd/siam"},{"title":"SKQD Helpers","href":"/reference/skqd/helpers"}]}]}]},{"tab":"API Reference","groups":[{"group":"API Reference","pages":[{"title":"Submit Circuit","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /circuits","href":"/api-reference/submit-circuit"},{"title":"Transpile Circuit","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /circuits/transpile","href":"/api-reference/transpile-circuit"},{"title":"Build Lr Qaoa Circuit","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /circuits/lr_qaoa","href":"/api-reference/build-lr-qaoa-circuit"},{"title":"Backpropagate Observables","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /circuits/{circuit_id}/backpropagate_observables","href":"/api-reference/backpropagate-observables"},{"title":"Compute Analytics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /circuits/{circuit_id}/compute_analytics/{analytics_type}","href":"/api-reference/compute-analytics"},{"title":"Get Circuit","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /circuits/{circuit_id}","href":"/api-reference/get-circuit"},{"title":"Delete Circuit","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json delete /circuits/{circuit_id}","href":"/api-reference/delete-circuit"},{"title":"Get Circuit By Hash","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/circuits/{circuit_hash}","href":"/api-reference/get-circuit-by-hash"},{"title":"Post Metrics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /experiments/{experiment_id}/circuits/{circuit_hash}/metrics","href":"/api-reference/post-metrics"},{"title":"Get Analytics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /circuits/{circuit_id}/metrics","href":"/api-reference/get-analytics"},{"title":"Get Metrics Evolution","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /circuits/{circuit_id}/metrics_evolution","href":"/api-reference/get-metrics-evolution"},{"title":"Collect Csp Report","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /csp","href":"/api-reference/collect-csp-report"},{"title":"List Devices Endpoint","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /devices","href":"/api-reference/list-devices-endpoint"},{"title":"Get Device Endpoint","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /devices/{device_id}","href":"/api-reference/get-device-endpoint"},{"title":"Get Device Gate Map","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /devices/{device_id}/gate_map","href":"/api-reference/get-device-gate-map"},{"title":"List Experiments","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments","href":"/api-reference/list-experiments"},{"title":"Create Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /experiments","href":"/api-reference/create-experiment"},{"title":"Init Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /experiments/init","href":"/api-reference/init-experiment"},{"title":"Get Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}","href":"/api-reference/get-experiment"},{"title":"Update Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json put /experiments/{experiment_id}","href":"/api-reference/update-experiment"},{"title":"Delete Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json delete /experiments/{experiment_id}","href":"/api-reference/delete-experiment"},{"title":"Post Metrics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /experiments/{experiment_id}/metrics","href":"/api-reference/post-metrics-1"},{"title":"List Circuits","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/circuits","href":"/api-reference/list-circuits"},{"title":"List Jobs","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/jobs","href":"/api-reference/list-jobs"},{"title":"List Artifacts","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/artifacts","href":"/api-reference/list-artifacts"},{"title":"Get Artifact","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/artifacts/{artifact_name}","href":"/api-reference/get-artifact"},{"title":"Submit Local Job","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /jobs","href":"/api-reference/submit-local-job"},{"title":"Post Metrics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /experiments/{experiment_id}/jobs/{job_id}/metrics","href":"/api-reference/post-metrics-2"},{"title":"Get Job","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /jobs/{job_id}","href":"/api-reference/get-job"},{"title":"Get Local Job By Hash","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /experiments/{experiment_id}/jobs/{job_hash}","href":"/api-reference/get-local-job-by-hash"},{"title":"Cancel Job","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /jobs/{job_id}/cancel","href":"/api-reference/cancel-job"},{"title":"Restart Job","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /jobs/{job_id}/restart","href":"/api-reference/restart-job"},{"title":"Get User","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /user","href":"/api-reference/get-user"},{"title":"Data Loading","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /data_loading","href":"/api-reference/data-loading"},{"title":"Data Loading Estimates","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /data_loading_estimates","href":"/api-reference/data-loading-estimates"},{"title":"Flow","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /flow","href":"/api-reference/flow"},{"title":"Run","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /run","href":"/api-reference/run"},{"title":"Compression","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /compression","href":"/api-reference/compression"},{"title":"Compression Estimates","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /compression_estimates","href":"/api-reference/compression-estimates"},{"title":"Postprocess Counts","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /postprocess","href":"/api-reference/postprocess-counts"},{"title":"Variational","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /variational","href":"/api-reference/variational"},{"title":"Pretraining","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /pretraining","href":"/api-reference/pretraining"},{"title":"Postprocess Skqd","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /postprocess_skqd","href":"/api-reference/postprocess-skqd"},{"title":"Create New Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/create_new_experiment","href":"/api-reference/create-new-experiment"},{"title":"List Experiments Mcp","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/","href":"/api-reference/list-experiments-mcp"},{"title":"Get Experiment By Name","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/by_name/{experiment_name}","href":"/api-reference/get-experiment-by-name"},{"title":"Get Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}","href":"/api-reference/get-experiment-1"},{"title":"Update Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json put /ai/{experiment_id}","href":"/api-reference/update-experiment-1"},{"title":"Get Experiment Url On Dashboard By Name","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/dashboard_url_by_name/{experiment_name}","href":"/api-reference/get-experiment-url-on-dashboard-by-name"},{"title":"List Circuits In Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}/circuits","href":"/api-reference/list-circuits-in-experiment"},{"title":"List Jobs","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}/jobs","href":"/api-reference/list-jobs-1"},{"title":"Log Artifact In Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/{experiment_id}/log_artifact","href":"/api-reference/log-artifact-in-experiment"},{"title":"List Artifacts In Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}/artifacts","href":"/api-reference/list-artifacts-in-experiment"},{"title":"Get Artifact In Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}/artifact","href":"/api-reference/get-artifact-in-experiment"},{"title":"Get Artifact Content In Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}/artifact/content","href":"/api-reference/get-artifact-content-in-experiment"},{"title":"Get Artifact Download Url In Experiment","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/{experiment_id}/artifact/download_url","href":"/api-reference/get-artifact-download-url-in-experiment"},{"title":"Submit Circuit For Analytics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/submit_circuit_for_analytics","href":"/api-reference/submit-circuit-for-analytics"},{"title":"Backpropagate Observables Mcp","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/backpropagate_observables","href":"/api-reference/backpropagate-observables-mcp"},{"title":"Get Circuit By Id","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/circuit/{circuit_id}","href":"/api-reference/get-circuit-by-id"},{"title":"Get Circuit Metrics Evolution","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/circuit/{circuit_id}/metrics_evolution","href":"/api-reference/get-circuit-metrics-evolution"},{"title":"Compute Circuit Analytics","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/compute_circuit_analytics","href":"/api-reference/compute-circuit-analytics"},{"title":"List Children Circuits","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/circuit/{circuit_id}/children","href":"/api-reference/list-children-circuits"},{"title":"List Jobs For Circuit","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/circuit/{circuit_id}/jobs","href":"/api-reference/list-jobs-for-circuit"},{"title":"Transpile Circuits","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/transpile_circuits","href":"/api-reference/transpile-circuits"},{"title":"Get Job Results And Status","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/jobs/{job_id}/results","href":"/api-reference/get-job-results-and-status"},{"title":"Cancel Job","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/jobs/{job_id}/cancel","href":"/api-reference/cancel-job-1"},{"title":"Restart Job","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/jobs/{job_id}/restart","href":"/api-reference/restart-job-1"},{"title":"List Qpus And Simulators","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/list_qpus_and_simulators","href":"/api-reference/list-qpus-and-simulators"},{"title":"Get Device Details","description":"Get one backend with its basis gates and qubit connectivity.\n\nUse this tool when a workflow needs the hardware constraints of a specific\nbackend rather than the whole catalog: which gates it supports and which\nqubit pairs are physically coupled. Those constraints determine what\n``transpile_circuits`` can target.\n\nWhen to Use:\n - Call this after ``list_qpus_and_simulators`` has narrowed the choice to\n one ``device_id``.\n - Call this before transpiling or before explaining why a circuit needs\n routing on a given backend.\n\nConstraints:\n - ``operation_names`` and ``coupling_map`` are ``null`` for backends that\n publish no transpilation target, which is common for simulators.\n - ``status`` and ``pending_jobs`` are point-in-time snapshots.\n\nNotes:\n - ``coupling_map`` can hold hundreds of qubit pairs on large QPUs. Check\n ``coupling_map_edges`` first and summarize connectivity instead of\n pasting the full list into agent-facing output.\n\nArgs:\n device_id: Backend identifier returned by ``list_qpus_and_simulators``.\n user: Authenticated user resolved from the API key.\n db: Active database session.\n\nReturns:\n The backend record extended with basis gates and coupling map.\n\nRaises:\n HTTPException: Raised with ``404`` when no backend matches ``device_id``.","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/device/{device_id}","href":"/api-reference/get-device-details"},{"title":"Run Circuits On Qpu Or Simulator","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/run_circuits_on_qpu_or_simulator","href":"/api-reference/run-circuits-on-qpu-or-simulator"},{"title":"Compress Circuit With State Compression","description":"Submit state-compression jobs for existing or inline circuits.\n\nUse this tool when the caller wants to run Haiqu state compression on\neither an existing stored circuit or a new inline QASM payload. At least\none of ``circuit_ids`` or ``circuit_qasm`` must be supplied, and the\nresponse schema is a lightweight ``{\"context\": ...}`` wrapper rather than a\nstructured job object.\n\nWhen to Use:\n - Call this when the workflow needs a compressed or optimized circuit\n derived from an existing circuit or from inline QASM.\n - Call this before later execution or circuit analysis when the user\n wants Haiqu state compression applied first.\n\nConstraints:\n - Provide at least one of ``circuit_ids`` or ``circuit_qasm``.\n - The response is a lightweight context wrapper; use\n ``get_job_results_and_status`` to retrieve terminal outputs such as\n the generated circuit ID.\n - This docstring does not promise normalized ``404`` handling for every\n invalid circuit reference because the lower-layer compression path\n owns part of that behavior.\n\nNotes:\n - If inline QASM is provided, the endpoint may create a circuit first\n and then submit compression.\n - The created or reused input circuit is stored as ``input_circuit_id``\n in the job record.\n - There is no practical size limit on ``circuit_qasm``. For circuits\n already stored, prefer ``circuit_ids`` so large QASM payloads are\n sent at most once; never downscale an instance because its QASM\n looks large.\n\nThe batch of compression jobs could be submitted via `circuit_ids`. If both\n`circuit_ids` and `circuit_id` are provided, `circuit_ids` will be used and\n`circuit_id` will be ignored, it is deprecated.\n\nArgs:\n user: Authenticated user resolved from the API key.\n data: Compression payload. One of ``circuit_ids`` or ``circuit_qasm``\n must be provided.\n db: Active database session.\n\nReturns:\n A lightweight context wrapper summarizing the submission and next\n polling step.\n\nRaises:\n HTTPException: Raised with ``400`` when neither circuit input mode is\n provided, ``402`` when the caller cannot submit billable jobs, or\n ``404`` when the experiment is not available to the caller.","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/compress_circuit_with_state_compression","href":"/api-reference/compress-circuit-with-state-compression"},{"title":"Estimate State Compression","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/estimate_state_compression","href":"/api-reference/estimate-state-compression"},{"title":"Load Classical Data With Data Loading","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/load_classical_data_with_data_loading","href":"/api-reference/load-classical-data-with-data-loading"},{"title":"Estimate Data Loading","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/estimate_data_loading","href":"/api-reference/estimate-data-loading"},{"title":"List Haiqu Algorithms","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/qakb/algorithms","href":"/api-reference/list-haiqu-algorithms"},{"title":"Get Haiqu Algorithm Recipe","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /ai/qakb/algorithms/{algorithm_key}/recipe","href":"/api-reference/get-haiqu-algorithm-recipe"},{"title":"Build Lr Qaoa Circuit Mcp","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/build_lr_qaoa_circuit","href":"/api-reference/build-lr-qaoa-circuit-mcp"},{"title":"Postprocess Measurement Counts","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/postprocess_measurement_counts","href":"/api-reference/postprocess-measurement-counts"},{"title":"Run Variational Workload","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/run_variational_workload","href":"/api-reference/run-variational-workload"},{"title":"Postprocess Skqd Samples","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/postprocess_skqd_samples","href":"/api-reference/postprocess-skqd-samples"},{"title":"Run Hybrid Flow","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /ai/run_hybrid_flow","href":"/api-reference/run-hybrid-flow"},{"title":"Notify Certificate Code","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json post /certificate-codes/{code}/notify","href":"/api-reference/notify-certificate-code"},{"title":"Root","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /","href":"/api-reference/root"},{"title":"Version","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /version","href":"/api-reference/version"},{"title":"Get Benchmarks","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /help/benchmarks","href":"/api-reference/get-benchmarks"},{"title":"Health Live","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /health/live","href":"/api-reference/health-live"},{"title":"Health Ready","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /health/ready","href":"/api-reference/health-ready"},{"title":"Health Auth","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /health/auth","href":"/api-reference/health-auth"},{"title":"Mcp Meta","deprecated":null,"version":null,"openapi":"https://api.haiqu.ai/openapi.json get /mcp/meta","href":"/api-reference/mcp-meta"}]}]},{"tab":"Publications","pages":[{"title":"Publications","href":"/publications"}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/changelog"}]},{"tab":"FAQ","pages":[{"title":"FAQ","href":"/faq"}]}]},"title":"Run Circuits On Qpu Or Simulator - Haiqu","buildId":"dpl_HcHmUS6i3UwswnTHJUEdcTtwfdTQ","deploymentId":"dpl_HcHmUS6i3UwswnTHJUEdcTtwfdTQ","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BRm_l__d.js","utils-f1l1Oc-G.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-BlhqDhJO.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DHCB7rsC.js","snippetPresets-CYXLx6Hv.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-B78P2dEq.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-C4YLPVAh.js","shallow-vlLnTDkQ.js","getApiPlaygroundDisplay-D_98hhvf.js","CodeSnippet-DtnZHGqq.js","CodeSnippets-CLFb8KJt.js","Page-kQh739Uz.js","getPastedJson-Cq-zlbnU.js","icon-sN3t983t.js","MethodPill-P_YQ2s09.js","DuplicateIcon-BVzyNsGJ.js","createIcon-B3jqgqC6.js","DynamicMarkdown-Crwq6WG_.js","SectionHeading-C7pGS2Bb.js","axios-vUo_bRtp.js","Markdown-BuPH8yuW.js","clsx-CCOYKgaU.js","lib--scc4DXi.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-BnkC_6oA.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-BM4S31-f.js"]}