curl --request POST \
--url 'https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=' \
--header 'Content-Type: application/json' \
--data '
{
"circuit_ids": [
"circ-123"
],
"dry_run": true,
"experiment_id": "exp-123",
"program": {
"layers": [
{
"type": "input"
},
{
"device_id": "fake_kyiv",
"type": "device"
}
],
"schema_version": 1
},
"shots": 1024
}
'import requests
url = "https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY="
payload = {
"circuit_ids": ["circ-123"],
"dry_run": True,
"experiment_id": "exp-123",
"program": {
"layers": [
{ "type": "input" },
{
"device_id": "fake_kyiv",
"type": "device"
}
],
"schema_version": 1
},
"shots": 1024
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
circuit_ids: ['circ-123'],
dry_run: true,
experiment_id: 'exp-123',
program: {
layers: [{type: 'input'}, {device_id: 'fake_kyiv', type: 'device'}],
schema_version: 1
},
shots: 1024
})
};
fetch('https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'circuit_ids' => [
'circ-123'
],
'dry_run' => true,
'experiment_id' => 'exp-123',
'program' => [
'layers' => [
[
'type' => 'input'
],
[
'device_id' => 'fake_kyiv',
'type' => 'device'
]
],
'schema_version' => 1
],
'shots' => 1024
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY="
payload := strings.NewReader("{\n \"circuit_ids\": [\n \"circ-123\"\n ],\n \"dry_run\": true,\n \"experiment_id\": \"exp-123\",\n \"program\": {\n \"layers\": [\n {\n \"type\": \"input\"\n },\n {\n \"device_id\": \"fake_kyiv\",\n \"type\": \"device\"\n }\n ],\n \"schema_version\": 1\n },\n \"shots\": 1024\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=")
.header("Content-Type", "application/json")
.body("{\n \"circuit_ids\": [\n \"circ-123\"\n ],\n \"dry_run\": true,\n \"experiment_id\": \"exp-123\",\n \"program\": {\n \"layers\": [\n {\n \"type\": \"input\"\n },\n {\n \"device_id\": \"fake_kyiv\",\n \"type\": \"device\"\n }\n ],\n \"schema_version\": 1\n },\n \"shots\": 1024\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"circuit_ids\": [\n \"circ-123\"\n ],\n \"dry_run\": true,\n \"experiment_id\": \"exp-123\",\n \"program\": {\n \"layers\": [\n {\n \"type\": \"input\"\n },\n {\n \"device_id\": \"fake_kyiv\",\n \"type\": \"device\"\n }\n ],\n \"schema_version\": 1\n },\n \"shots\": 1024\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>",
"context": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}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.
curl --request POST \
--url 'https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=' \
--header 'Content-Type: application/json' \
--data '
{
"circuit_ids": [
"circ-123"
],
"dry_run": true,
"experiment_id": "exp-123",
"program": {
"layers": [
{
"type": "input"
},
{
"device_id": "fake_kyiv",
"type": "device"
}
],
"schema_version": 1
},
"shots": 1024
}
'import requests
url = "https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY="
payload = {
"circuit_ids": ["circ-123"],
"dry_run": True,
"experiment_id": "exp-123",
"program": {
"layers": [
{ "type": "input" },
{
"device_id": "fake_kyiv",
"type": "device"
}
],
"schema_version": 1
},
"shots": 1024
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
circuit_ids: ['circ-123'],
dry_run: true,
experiment_id: 'exp-123',
program: {
layers: [{type: 'input'}, {device_id: 'fake_kyiv', type: 'device'}],
schema_version: 1
},
shots: 1024
})
};
fetch('https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'circuit_ids' => [
'circ-123'
],
'dry_run' => true,
'experiment_id' => 'exp-123',
'program' => [
'layers' => [
[
'type' => 'input'
],
[
'device_id' => 'fake_kyiv',
'type' => 'device'
]
],
'schema_version' => 1
],
'shots' => 1024
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY="
payload := strings.NewReader("{\n \"circuit_ids\": [\n \"circ-123\"\n ],\n \"dry_run\": true,\n \"experiment_id\": \"exp-123\",\n \"program\": {\n \"layers\": [\n {\n \"type\": \"input\"\n },\n {\n \"device_id\": \"fake_kyiv\",\n \"type\": \"device\"\n }\n ],\n \"schema_version\": 1\n },\n \"shots\": 1024\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=")
.header("Content-Type", "application/json")
.body("{\n \"circuit_ids\": [\n \"circ-123\"\n ],\n \"dry_run\": true,\n \"experiment_id\": \"exp-123\",\n \"program\": {\n \"layers\": [\n {\n \"type\": \"input\"\n },\n {\n \"device_id\": \"fake_kyiv\",\n \"type\": \"device\"\n }\n ],\n \"schema_version\": 1\n },\n \"shots\": 1024\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/ai/run_hybrid_flow?HAIQU_API_KEY=")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"circuit_ids\": [\n \"circ-123\"\n ],\n \"dry_run\": true,\n \"experiment_id\": \"exp-123\",\n \"program\": {\n \"layers\": [\n {\n \"type\": \"input\"\n },\n {\n \"device_id\": \"fake_kyiv\",\n \"type\": \"device\"\n }\n ],\n \"schema_version\": 1\n },\n \"shots\": 1024\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>",
"context": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}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]].
Show child attributes
Show child attributes
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.