> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-codex-docs-audit-20260719-0149.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute Workflow

> Execute a workflow with the provided input data. Workflows can run in streaming or batch mode.

**Execution Modes:**
- **Streaming (`stream=true`)**: Real-time step-by-step execution updates via SSE
- **Non-Streaming (`stream=false`)**: Complete workflow execution with final result

**Workflow Execution Process:**
1. Input validation against workflow schema
2. Sequential or parallel step execution based on workflow design
3. Data flow between steps with transformation
4. Error handling and automatic retries where configured
5. Final result compilation and response

**Session Management:**
Workflows support session continuity for stateful execution across multiple runs.



## OpenAPI

````yaml post /workflows/{workflow_id}/runs
openapi: 3.1.0
info:
  title: Agno API Reference
  description: The all-in-one, private, secure agent platform that runs in your cloud.
  version: 2.7.4
servers: []
security: []
paths:
  /workflows/{workflow_id}/runs:
    post:
      tags:
        - Workflows
      summary: Execute Workflow
      description: >-
        Execute a workflow with the provided input data. Workflows can run in
        streaming or batch mode.


        **Execution Modes:**

        - **Streaming (`stream=true`)**: Real-time step-by-step execution
        updates via SSE

        - **Non-Streaming (`stream=false`)**: Complete workflow execution with
        final result


        **Workflow Execution Process:**

        1. Input validation against workflow schema

        2. Sequential or parallel step execution based on workflow design

        3. Data flow between steps with transformation

        4. Error handling and automatic retries where configured

        5. Final result compilation and response


        **Session Management:**

        Workflows support session continuity for stateful execution across
        multiple runs.
      operationId: create_workflow_run
      parameters:
        - name: workflow_id
          in: path
          required: true
          schema:
            type: string
            title: Workflow Id
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_create_workflow_run'
      responses:
        '200':
          description: Workflow executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunSchema'
            text/event-stream:
              example: |+
                event: RunStarted
                data: {"content": "Hello!", "run_id": "123..."}

        '202':
          description: Background run accepted when `background=true` and `stream=false`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BackgroundRunResponse'
        '400':
          description: Invalid input data or workflow configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenResponse'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Workflow execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - {}
        - HTTPBearer: []
components:
  schemas:
    Body_create_workflow_run:
      properties:
        message:
          type: string
          title: Message
          description: The input message or prompt to send to the workflow
        stream:
          type: boolean
          title: Stream
          description: Enable streaming responses via Server-Sent Events (SSE)
          default: true
        background:
          type: boolean
          title: Background
          description: >-
            Run workflow in background (survives client disconnect). Requires
            database. Use /resume to reconnect.
          default: false
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: >-
            Session ID for conversation continuity. If not provided, a new
            session is created
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: User identifier for tracking and personalization
        version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Version
          description: Workflow version to use for this run
        factory_input:
          anyOf:
            - type: string
            - type: 'null'
          title: Factory Input
          description: >-
            JSON object with factory-specific parameters for dynamic workflow
            construction
      type: object
      required:
        - message
      title: Body_create_workflow_run
    WorkflowRunSchema:
      properties:
        run_id:
          type: string
          title: Run Id
          description: Unique identifier for the workflow run
        run_input:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Input
          description: Input provided to the workflow
        events:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Events
          description: Events generated during the workflow
        workflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Id
          description: Workflow ID that was executed
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: User ID associated with the run
        content:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Content
          description: Output content from the workflow
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
          description: Type of content returned
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
          description: Status of the workflow run
        step_results:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Step Results
          description: Results from each workflow step
        step_executor_runs:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Step Executor Runs
          description: Executor runs for each step
        step_requirements:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Step Requirements
          description: HITL step requirements (resolved state for historical display)
        pause_kind:
          anyOf:
            - type: string
            - type: 'null'
          title: Pause Kind
          description: 'Kind of HITL pause: ''step'' or ''executor'''
        paused_step_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Paused Step Name
          description: Name of the step that caused the pause
        paused_step_index:
          anyOf:
            - type: integer
            - type: 'null'
          title: Paused Step Index
          description: Index of the step that caused the pause
        metrics:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metrics
          description: Performance and usage metrics
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Run creation timestamp
        reasoning_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning Content
          description: Reasoning content if reasoning was enabled
        reasoning_steps:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Reasoning Steps
          description: List of reasoning steps
        references:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: References
          description: References cited in the workflow
        citations:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Citations
          description: Citations from the model (e.g., from Gemini grounding/search)
        reasoning_messages:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Reasoning Messages
          description: Reasoning process messages
        images:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Images
          description: Images included in the workflow
        videos:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Videos
          description: Videos included in the workflow
        audio:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Audio
          description: Audio files included in the workflow
        files:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Files
          description: Files included in the workflow
        response_audio:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response Audio
          description: Audio response if generated
      type: object
      required:
        - run_id
      title: WorkflowRunSchema
    BackgroundRunResponse:
      properties:
        run_id:
          type: string
          title: Run Id
          description: Unique identifier for the background run.
        session_id:
          type: string
          title: Session Id
          description: Session that contains the background run.
        status:
          type: string
          title: Status
          description: Initial run status.
      type: object
      required:
        - run_id
        - session_id
        - status
      title: BackgroundRunResponse
    BadRequestResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: BadRequestResponse
      example:
        detail: Bad request
        error_code: BAD_REQUEST
    UnauthenticatedResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: UnauthenticatedResponse
      example:
        detail: Unauthenticated access
        error_code: UNAUTHENTICATED
    ForbiddenResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
      type: object
      required:
        - detail
      title: ForbiddenResponse
      example:
        detail: Insufficient permissions
    NotFoundResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: NotFoundResponse
      example:
        detail: Not found
        error_code: NOT_FOUND
    ValidationErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: ValidationErrorResponse
      example:
        detail: Validation error
        error_code: VALIDATION_ERROR
    InternalServerErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: InternalServerErrorResponse
      example:
        detail: Internal server error
        error_code: INTERNAL_SERVER_ERROR
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````