Base

Experimental Run Flow

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:

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.

post/api/v1/run/advanced/{flow_id_or_name}

Path parameters

flow_id_or_namestring required

Request body

outputsstring[] nullable

session_idstring nullable

streamboolean

tweaksTweaks

A dictionary of tweaks to adjust the flow's execution. Allows customizing flow behavior dynamically. All tweaks are overridden by the input values.

Example request

{
  "inputs": [
    {
      "components": [
        "components_id",
        "Component Name"
      ],
      "input_value": "input_value",
      "session": "session_id"
    }
  ],
  "tweaks": {
    "Component Name": {
      "parameter_name": "value"
    },
    "component_id": {
      "parameter_name": "value"
    },
    "parameter_name": "value",
    "stream": false,
    "temperature": 0.7
  }
}

Response

Successful Response

session_idstring nullable

Changes

Changed in 4 of the 21 revisions of this API.247

Jun 8, 2026a5c4fa6a88f711See the full diff
- ●
  deleted the query request parameter user_id
  request-parameter-removed
- ○
  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
  request-property-list-of-types-widened
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 13, 2026acd160326a881See the full diff
- ○
  added the optional property outputs/anyOf[subschema #1]/items/outputs/items/anyOf[subschema #1: ResultData]/token_usage to the response with the 200 status
  response-optional-property-added
Mar 12, 2026830c311182152See the full diff
- ○
  added the optional property detail/items/ctx to the response with the 422 status
  response-optional-property-added
- ○
  added the optional property detail/items/input to the response with the 422 status
  response-optional-property-added
This revision also has 12 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Oct 16, 20259bd3e81318d7233See the full diff
- ▲
  for the path request parameter flow_id_or_name, the type/format was changed from string/ to string/uuid
  request-parameter-type-changed
- ▲
  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
  request-property-list-of-types-narrowed
- ●
  removed the request property inputs/anyOf[subschema #1]/items/client_request_time
  request-property-removed
- ●
  removed the optional property detail/items/ctx from the response with the 422 status
  response-optional-property-removed
- ●
  removed the optional property detail/items/input from the response with the 422 status
  response-optional-property-removed
- ○
  api operation id experimental_run_flow_api_v1_run_advanced__flow_id_or_name__post removed and replaced with experimental_run_flow_api_v1_run_advanced__flow_id__post
  api-operation-id-removed
- ○
  added ResultData-Output to the outputs/anyOf[subschema #1]/items/outputs/items/ response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  removed ResultData from the outputs/anyOf[subschema #1]/items/outputs/items/ response property anyOf list for the response status 200
  response-property-any-of-removed
This revision also has 62 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history