> ## Documentation Index
> Fetch the complete documentation index at: https://docs.haiqu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run 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=true`` first for an unfamiliar program, to
      validate the layer pipeline before spending credits.

Constraints:
    - ``program`` must validate against the hybrid program schema:
      ``{'schema_version': 1, 'layers': [...]}`` with a ``type`` discriminator
      on each layer. Invalid programs are rejected with ``422`` naming the
      offending layer.
    - Do not invent layer configurations. Build the program with the Haiqu SDK
      or copy it from the hybrid flow documentation.
    - ``circuit_ids`` must reference stored circuits.
    - Non-dry-run flows are asynchronous and billable. Poll with
      ``get_job_results_and_status``; stop one with ``cancel_job``.

Notes:
    - Device credentials belong in ``device_credentials``, in the same form
      ``run_circuits_on_qpu_or_simulator`` documents for ``options``.
    - For single-stage work, prefer the dedicated tools such as
      ``transpile_circuits`` or ``run_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.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json post /ai/run_hybrid_flow
openapi: 3.1.0
info:
  title: Haiqu API
  summary: Haiqu RESTful API service.
  description: Cloud service providing the access to Haiqu cloud runtime
  contact:
    name: Haiqu Inc.
    url: https://haiqu.ai/
    email: info@haiqu.ai
  version: 1.5.0
servers: []
security: []
paths:
  /ai/run_hybrid_flow:
    post:
      summary: Run Hybrid Flow
      description: >-
        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=true`` first for an unfamiliar program, to
              validate the layer pipeline before spending credits.

        Constraints:
            - ``program`` must validate against the hybrid program schema:
              ``{'schema_version': 1, 'layers': [...]}`` with a ``type`` discriminator
              on each layer. Invalid programs are rejected with ``422`` naming the
              offending layer.
            - Do not invent layer configurations. Build the program with the Haiqu SDK
              or copy it from the hybrid flow documentation.
            - ``circuit_ids`` must reference stored circuits.
            - Non-dry-run flows are asynchronous and billable. Poll with
              ``get_job_results_and_status``; stop one with ``cancel_job``.

        Notes:
            - Device credentials belong in ``device_credentials``, in the same form
              ``run_circuits_on_qpu_or_simulator`` documents for ``options``.
            - For single-stage work, prefer the dedicated tools such as
              ``transpile_circuits`` or ``run_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.
      operationId: run_hybrid_flow
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContextHybridSubmitModel'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextHybridJobModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    ContextHybridSubmitModel:
      properties:
        experiment_id:
          type: string
          title: Experiment Id
        program:
          additionalProperties: true
          type: object
          title: Program
          description: >-
            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.
        circuit_ids:
          items:
            type: string
          type: array
          title: Circuit Ids
          description: Circuits the flow consumes, from prior MCP responses.
        shots:
          type: integer
          title: Shots
          default: 1000
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          default: ''
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          default: ''
        parameters:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Parameters
          description: Optional parameter bindings per circuit.
        observables:
          anyOf:
            - items:
                items:
                  prefixItems:
                    - items:
                        type: string
                      type: array
                    - items:
                        type: number
                      type: array
                  type: array
                  maxItems: 2
                  minItems: 2
                type: array
              type: array
            - type: 'null'
          title: Observables
          description: >-
            Optional observables per circuit, each as `[[pauli_strings],
            [coefficients]]`.
        device_credentials:
          additionalProperties: true
          type: object
          title: Device Credentials
          description: >-
            Credentials required by the flow's device layer, such as
            `ibm_quantum_token`.
        dry_run:
          type: boolean
          title: Dry Run
          description: >-
            Validate and plan the flow without executing it. Use this first for
            an unfamiliar program.
          default: false
      type: object
      required:
        - experiment_id
        - program
        - circuit_ids
      title: ContextHybridSubmitModel
      description: |-
        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.
      examples:
        - 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
    ContextHybridJobModel:
      properties:
        job_id:
          type: string
          title: Job Id
        context:
          type: string
          title: Context
      type: object
      required:
        - job_id
        - context
      title: ContextHybridJobModel
      description: |-
        Represent context returned after a hybrid flow submission.

        Attributes:
            job_id: Created job identifier.
            context: Submission summary and next polling step.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

````