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

# Experimental Run Flow

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

Executes a specified flow by ID with optional input values, output selection, tweaks, and streaming capability.

This endpoint supports running flows with caching to enhance performance and efficiency.

### Parameters:
- `flow` (Flow): The flow object to be executed, resolved via dependency injection.
- `inputs` (List[InputValueRequest], optional): A list of inputs specifying the input values and components
  for the flow. Each input can target specific components and provide custom values.
- `outputs` (List[str], optional): A list of output names to retrieve from the executed flow.
  If not provided, all outputs are returned.
- `tweaks` (Optional[Tweaks], optional): A dictionary of tweaks to customize the flow execution.
  The tweaks can be used to modify the flow's parameters and components.
  Tweaks can be overridden by the input values.
- `stream` (bool, optional): Specifies whether the results should be streamed. Defaults to False.
- `session_id` (Union[None, str], optional): An optional session ID to utilize existing session data for the flow
  execution.
- `api_key_user` (User): The user associated with the current API key. Automatically resolved from the API key.

### Returns:
A `RunResponse` object containing the selected outputs (or all if not specified) of the executed flow
and the session ID.
The structure of the response accommodates multiple inputs, providing a nested list of outputs for each input.

### Raises:
HTTPException: Indicates issues with finding the specified flow, invalid input formats, or internal errors during
flow execution.

### Example usage:
```json
POST /run/flow_id
x-api-key: YOUR_API_KEY
Payload:
{
    "inputs": [
        {"components": ["component1"], "input_value": "value1"},
        {"components": ["component3"], "input_value": "value2"}
    ],
    "outputs": ["Component Name", "component_id"],
    "tweaks": {"parameter_name": "value", "Component Name": {"parameter_name": "value"}, "component_id": {"parameter_name": "value"}}
    "stream": false
}
```

This endpoint facilitates complex flow executions with customized inputs, outputs, and configurations,
catering to diverse application requirements.

## Path parameters

- `flow_id_or_name` string, required

## Request body

- BodyExperimentalRunFlowApiV1RunAdvancedFlowIdOrNamePost
  - `inputs` InputValueRequest[], nullable
    - `client_request_time` integer, nullable — Client-side timestamp in milliseconds when the request was initiated. Used to calculate accurate end-to-end duration.
    - `components` string[], nullable
    - `input_value` string, nullable
    - `session` string, nullable
    - `type` 'chat' | 'text' | 'any', nullable — Defines on which components the input value should be applied. 'any' applies to all input components.
  - `outputs` string[], nullable
  - `session_id` string, nullable
  - `stream` boolean
  - `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.

## Response `200`

Successful Response

- RunResponse — Run response schema.
  - `outputs` RunOutputs[], nullable
    - `inputs` object
    - `outputs` ResultData[]
      - `artifacts` unknown
      - `component_display_name` string, nullable
      - `component_id` string, nullable
      - `duration` string, nullable
      - `logs` object, nullable
      - `messages` ChatOutputResponse[], nullable
        - `component_id` string, nullable
        - `files` LfxUtilsSchemasFile[]
          - `name` string, required
          - `path` string, required
          - `type` string, required
        - `message` union, required
          - string
          - union[]
            - union
              - …
        - `sender` string, nullable
        - `sender_name` string, nullable
        - `session_id` string, nullable
        - `stream_url` string, nullable
        - `type` string, required
      - `outputs` object, nullable
      - `results` unknown
      - `timedelta` number, nullable
      - `token_usage` Usage — Token usage information from LLM responses.
        - `input_tokens` integer, nullable
        - `output_tokens` integer, nullable
        - `total_tokens` integer, nullable
      - `used_frozen_result` boolean, nullable
  - `session_id` string, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-06-08** `a5c4fa6a88f7` — 1 warning, 1 info
  - deleted the `query` request parameter `user_id`
  - request property `tweaks/anyOf[subschema #1: Tweaks]/additionalProperties/` list-of-types was widened by adding types `boolean, integer and number` to media type `application/json`
- **2026-04-13** `acd160326a88` — 1 info
  - added the optional property `outputs/anyOf[subschema #1]/items/outputs/items/anyOf[subschema #1: ResultData]/token_usage` to the response with the `200` status
- **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-10-16** `9bd3e81318d7` — 2 breaking, 3 warning, 3 info
  - for the `path` request parameter `flow_id_or_name`, the type/format was changed from `string`/`` to `string`/`uuid`
  - request property `tweaks/anyOf[subschema #1: Tweaks]/additionalProperties/` list-of-types was narrowed by removing types `boolean, integer and number` from media type `application/json`
  - removed the request property `inputs/anyOf[subschema #1]/items/client_request_time`
  - removed the optional property `detail/items/ctx` from the response with the `422` status
  - …4 more

[Change history](https://skmtc.dev/langflow-ai/apis/langflow/changes/api/v1/run/advanced/: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)