---
title: "Simplified Run Flow"
method: POST
path: "/api/v1/run/{flow_id_or_name}"
tags: ["Base"]
---

# Simplified Run Flow

`POST /api/v1/run/{flow_id_or_name}`

Executes a specified flow by ID with support for streaming and telemetry (API key auth).

This endpoint executes a flow identified by ID or name, with options for streaming the response
and tracking execution metrics. It handles both streaming and non-streaming execution modes.
This endpoint uses API key authentication (Bearer token).

Args:
    background_tasks (BackgroundTasks): FastAPI background task manager
    flow (FlowRead | None): The flow to execute, loaded via dependency
    input_request (SimplifiedAPIRequest | None): Input parameters for the flow
    stream (bool): Whether to stream the response
    api_key_user (UserRead): Authenticated user from API key
    context (dict | None): Optional context to pass to the flow
    http_request (Request): The incoming HTTP request for extracting global variables

Returns:
    Union[StreamingResponse, RunResponse]: Either a streaming response for real-time results
    or a RunResponse with the complete execution results

Raises:
    HTTPException: For flow not found (404) or invalid input (400)
    APIException: For internal execution errors (500)

Notes:
    - Supports both streaming and non-streaming execution modes
    - Tracks execution time and success/failure via telemetry
    - Handles graceful client disconnection in streaming mode
    - Provides detailed error handling with appropriate HTTP status codes
    - Extracts global variables from HTTP headers with prefix X-LANGFLOW-GLOBAL-VAR-*
    - Merges extracted variables with the context parameter as "request_variables"
    - In streaming mode, uses EventManager to handle events:
        - "add_message": New messages during execution
        - "token": Individual tokens during streaming
        - "end": Final execution result
    - Authentication: Requires API key (Bearer token)

## Path parameters

- `flow_id_or_name` string, required

## Query parameters

- `stream` boolean

## Request body

- BodySimplifiedRunFlowApiV1RunFlowIdOrNamePost
  - `context` object, nullable
  - `input_request` SimplifiedAPIRequest
    - `input_type` 'chat' | 'text' | 'any', nullable — The input type
    - `input_value` string, nullable — The input value
    - `output_component` string, nullable — If there are multiple output components, you can specify the component to get the output from.
    - `output_type` 'chat' | 'text' | 'any' | 'debug', nullable — The output type
    - `session_id` string, nullable — The session id
    - `tweaks` Tweaks — A dictionary of tweaks to adjust the flow's execution. Allows customizing flow behavior dynamically. All tweaks are overridden by the input values.
    - `user_id` string, nullable — Optional end-user identifier forwarded to tracing providers (e.g. Langfuse) as the trace's user_id. Does not affect authentication or authorization — the API key owner remains the effective Langflow user.

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

## Changes

- **2026-06-08** `a5c4fa6a88f7` — 1 warning, 2 info
  - deleted the `query` request parameter `user_id`
  - added the new optional request property `input_request/anyOf[subschema #1: SimplifiedAPIRequest]/user_id`
  - request property `input_request/anyOf[subschema #1: SimplifiedAPIRequest]/tweaks/anyOf[subschema #1: Tweaks]/additionalProperties/` list-of-types was widened by adding types `boolean, integer and number` to media type `application/json`
- **2026-03-12** `830c31118215` — 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2025-12-23** `b0ee9ddb8d9f` — 2 breaking, 2 info
  - removed `#/components/schemas/SimplifiedAPIRequest, subschema #2` from the request body `anyOf` list
  - the request's body type/format changed from ``/`` to `object`/``
  - added the new optional request property `context`
  - added the new optional request property `input_request`
- **2025-10-16** `840e512f9378` — 1 breaking, 2 warning, 1 info
  - the request's body type/format changed from `object`/`` to ``/``
  - removed the request property `context`
  - removed the request property `input_request`
  - added `#/components/schemas/SimplifiedAPIRequest, subschema #2` to the request body `anyOf` list
- …earlier changes not shown

[Full history](https://skmtc.dev/langflow-ai/apis/langflow/changes/api/v1/run/:flow_id_or_name/post.md)

---

[API](https://skmtc.dev/langflow-ai/apis/langflow.md) · [All operations](https://skmtc.dev/langflow-ai/apis/langflow/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/langflow-ai/langflow/revisions/22962dc5e81b/schema)