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

# Create Run

> Queue a run of a Flow with the given input

## Behavior

* **Asynchronous.** This call queues the run and returns immediately with the new run's `id` — it does not wait for the run to finish.
* **Input** must match the Flow's active version input schema.
* Poll [Get Run](/api-reference/flows/get-run) with the returned `id` to check status and retrieve the result.
* Returns `404` if `flowId` does not exist, or belongs to a different customer.


## OpenAPI

````yaml POST /flows/{flowId}/runs
openapi: 3.0.1
info:
  version: 1.0.0
  title: Diligent Flows
  description: Trigger a Flow run and retrieve its result.
servers:
  - url: https://api.godiligent.ai
    description: Production
  - url: https://api.sandbox.godiligent.ai
    description: Sandbox
security:
  - xApiKey: []
tags:
  - name: Flows
    description: Trigger a Flow run and retrieve its result
paths:
  /flows/{flowId}/runs:
    post:
      tags:
        - Flows
      summary: Create Run
      description: >-
        Queues a run of the Flow's active version. Execution happens
        asynchronously — this call returns immediately with the new run's id;
        poll GET /flow-runs/{runId} for the result.
      operationId: queueRun
      parameters:
        - name: flowId
          in: path
          description: The Flow to run
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueueRunRequest'
            example:
              input:
                fullName: Sossio Sorrentino
                email: sossio.sorrentino@example.com
                phone: '+393510000000'
                country: Italy
                city: Napoli
      responses:
        '202':
          description: Run queued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueRunResponse'
              example:
                id: 8f14e45f-ceea-4c6b-a1b2-3c4d5e6f7890
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: VALIDATION_ERROR
                message: Request body failed validation.
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: UNAUTHORIZED
                message: API key is missing or invalid.
        '404':
          description: Flow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: FLOW_NOT_FOUND
                message: 'Flow not found: flow-123'
        '500':
          description: Internal Server Error
      security:
        - xApiKey: []
components:
  schemas:
    QueueRunRequest:
      type: object
      required:
        - input
      properties:
        input:
          type: object
          additionalProperties: true
          description: Run input. Must match the Flow's active version input schema.
    QueueRunResponse:
      type: object
      required:
        - id
      properties:
        id:
          type: string
          description: >-
            The new run's id. Use it with GET /flow-runs/{runId} to poll for the
            result.
    ErrorResponse:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: >-
            Machine-readable error code, e.g. FLOW_NOT_FOUND, RUN_NOT_FOUND,
            VALIDATION_ERROR.
        message:
          type: string
  securitySchemes:
    xApiKey:
      type: apiKey
      name: X-API-KEY
      in: header

````