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

# Execute a flow

> Execute a flow's latest saved version, with values for its input nodes.



## OpenAPI

````yaml api-reference/openapi.yaml POST /v1/flows/{flow_id}/execute
openapi: 3.0.3
info:
  title: QX API
  version: '1.0'
  description: >-
    Run what you build in QX from your own code. Message agents, execute flows
    and grids, and read their results.
servers:
  - url: https://api.qxlabs.com
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: >-
      Message agents through OpenAI's Responses API, so OpenAI's SDKs work with
      a QX API key.
  - name: Flows
    description: Execute flows and follow their executions.
  - name: Grids
    description: Execute grids, follow their executions and read their rows.
paths:
  /v1/flows/{flow_id}/execute:
    post:
      tags:
        - Flows
      summary: Execute a flow
      description: >
        Executes the flow's latest saved version and returns the execution's ID.
        Poll the execution endpoint for its progress and results.

        The flow endpoint lists the fields each input node takes. Input values
        are checked when the execution reaches each input node, so a wrong value
        shows up as a failed execution, with the field's error message.

        The execution uses your org's credits, as it would in the app, and
        appears in the flow's execution history there.
      operationId: executeFlow
      parameters:
        - name: flow_id
          in: path
          required: true
          schema:
            type: string
          description: The flow's ID, as shown in its URL in the app
          example: c71a5f0e1d2b4a7e9a513f6f0d2b8e10
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                inputs:
                  type: object
                  description: >-
                    Input node ID, then field name, then value. Leave it out for
                    flows with no input nodes
                  additionalProperties:
                    type: object
            example:
              inputs:
                UserInputNodex7q2m9ka4:
                  Company Name: Acme
                  Size: 51-500
      responses:
        '202':
          description: Execution started
          content:
            application/json:
              schema:
                type: object
                properties:
                  execution_id:
                    type: string
                    description: The execution's ID, the same one the app shows
                  flow_id:
                    type: string
              example:
                execution_id: 9b2e4d713a5c4f8bb6e21c7d9a0f3e58
                flow_id: c71a5f0e1d2b4a7e9a513f6f0d2b8e10
        '400':
          description: The request isn't valid JSON, or the flow can't be executed with it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: >-
                  This flow starts from a trigger, so it executes when the
                  trigger fires.
        '402':
          description: Your org is out of credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The flow is in your org but isn't shared with you
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: There's no such flow, or it belongs to another org
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Write rate limit exceeded for flows endpoints
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >
            curl
            https://api.qxlabs.com/v1/flows/c71a5f0e1d2b4a7e9a513f6f0d2b8e10/execute
            \
              -H "Authorization: Bearer <YOUR_QX_API_KEY>" \
              -H "Content-Type: application/json" \
              -d '{
                "inputs": {
                  "UserInputNodex7q2m9ka4": {"Company Name": "Acme", "Size": "51-500"}
                }
              }'
        - lang: python
          label: Python
          source: |
            import requests

            headers = {"Authorization": "Bearer <YOUR_QX_API_KEY>"}

            execution = requests.post(
                "https://api.qxlabs.com/v1/flows/c71a5f0e1d2b4a7e9a513f6f0d2b8e10/execute",
                json={"inputs": {"UserInputNodex7q2m9ka4": {"Company Name": "Acme", "Size": "51-500"}}},
                headers=headers,
            ).json()
            print(execution["execution_id"])
        - lang: typescript
          label: TypeScript
          source: >
            const headers = { Authorization: "Bearer <YOUR_QX_API_KEY>",
            "Content-Type": "application/json" };


            const response = await
            fetch("https://api.qxlabs.com/v1/flows/c71a5f0e1d2b4a7e9a513f6f0d2b8e10/execute",
            {
              method: "POST",
              headers,
              body: JSON.stringify({
                inputs: { "UserInputNodex7q2m9ka4": { "Company Name": "Acme", Size: "51-500" } },
              }),
            });

            const execution = await response.json();

            console.log(execution.execution_id);
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: What went wrong
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your QX API key. The `X-API-Key` header works too

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.