Run Hybrid Flow
Run a multi-stage hybrid flow as a single job.
Use this tool when a workload needs several Haiqu stages chained together — for example transpile, then run with error mitigation, then estimate observables — and the caller already has the flow definition. The whole pipeline executes as one job instead of separate tool calls.
When to Use:
- Call this when the user supplies a hybrid program or asks to run an existing flow.
- Call this with
dry_run=truefirst for an unfamiliar program, to validate the layer pipeline before spending credits.
Constraints:
programmust validate against the hybrid program schema:{'schema_version': 1, 'layers': [...]}with atypediscriminator on each layer. Invalid programs are rejected with422naming the offending layer.- Do not invent layer configurations. Build the program with the Haiqu SDK or copy it from the hybrid flow documentation.
circuit_idsmust reference stored circuits.- Non-dry-run flows are asynchronous and billable. Poll with
get_job_results_and_status; stop one withcancel_job.
Notes:
- Device credentials belong in
device_credentials, in the same formrun_circuits_on_qpu_or_simulatordocuments foroptions. - For single-stage work, prefer the dedicated tools such as
transpile_circuitsorrun_circuits_on_qpu_or_simulator; they have much simpler payloads.
Args: user: Authenticated user resolved from the API key. data: Flow definition, input circuits, and execution settings. db: Active database session.
Returns: The created job identifier with the next polling step.
Raises:
HTTPException: Raised with 402 when the caller cannot submit billable
jobs, 404 when the experiment is unavailable, or 422 when the
program definition is invalid.
Authorizations
Body
Define payload for a hybrid flow job.
Attributes: experiment_id: Parent experiment identifier. program: Hybrid program definition as a layer list. circuit_ids: Circuits the flow consumes. shots: Shots per circuit. name: Optional job name. description: Optional job description. parameters: Optional parameter bindings per circuit. observables: Optional observables per circuit. device_credentials: Backend credentials required by device layers. dry_run: Whether to validate the flow without executing it.
Hybrid program as {'schema_version': 1, 'layers': [...]}, where each layer is an object with a type discriminator such as input, device, transpilation, estimator, or a mitigation layer. The layer set is validated server-side and documented in the Haiqu hybrid flow reference; build it with the SDK when unsure.
Circuits the flow consumes, from prior MCP responses.
Optional parameter bindings per circuit.
Optional observables per circuit, each as [[pauli_strings], [coefficients]].
Credentials required by the flow's device layer, such as ibm_quantum_token.
Validate and plan the flow without executing it. Use this first for an unfamiliar program.