flow/docs/docs/API-Reference/api-flows-run.mdx

---
title: Flow trigger endpoints
slug: /api-flows-run
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Use the `/run` and `/webhook` endpoints to run flows.

To create, read, update, and delete flows, see [Flow management endpoints](/api-flows).

## Run flow

:::tip
Langflow automatically generates Python, JavaScript, and curl code snippets for the `/v1/run/$FLOW_ID` endpoint for all flows.
For more information, see [Generate API code snippets](/concepts-publish#generate-api-code-snippets).
:::

Execute a specified flow by ID or name.
Flow IDs can be found on the code snippets on the [**API access** pane](/concepts-publish#api-access) or in a flow's URL.

The following example runs the **Basic Prompting** template flow with flow parameters passed in the request body.
This flow requires a chat input string (`input_value`), and uses default values for all other parameters.

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID"

# Request payload
payload = {
    "input_value": "Tell me about something interesting!",
    "session_id": "chat-123",
    "input_type": "chat",
    "output_type": "chat",
    "output_component": ""
}

# Request headers
headers = {
    "Content-Type": "application/json",
    "x-api-key": "LANGFLOW_API_KEY"
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
  input_value: "Tell me about something interesting!",
  session_id: "chat-123",
  input_type: "chat",
  output_type: "chat",
  output_component: ""
};

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'LANGFLOW_API_KEY'
  },
  body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
  "$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -d '{
    "input_value": "Tell me about something interesting!",
    "session_id": "chat-123",
    "input_type": "chat",
    "output_type": "chat",
    "output_component": ""
  }'
```

</TabItem>
</Tabs>

The response from `/v1/run/$FLOW_ID` includes metadata, inputs, and outputs for the run.

<details>
<summary>Result</summary>

The following example illustrates a response from a Basic Prompting flow:

```json
{
  "session_id": "chat-123",
  "outputs": [{
    "inputs": {
      "input_value": "Tell me about something interesting!"
    },
    "outputs": [{
      "results": {
        "message": {
          "text": "Sure! Have you ever heard of the phenomenon known as \"bioluminescence\"? It's a fascinating natural occurrence where living organisms produce and emit light. This ability is found in various species, including certain types of jellyfish, fireflies, and deep-sea creatures like anglerfish.\n\nBioluminescence occurs through a chemical reaction in which a light-emitting molecule called luciferin reacts with oxygen, catalyzed by an enzyme called luciferase. The result is a beautiful glow that can serve various purposes, such as attracting mates, deterring predators, or luring prey.\n\nOne of the most stunning displays of bioluminescence can be seen in the ocean, where certain plankton emit light when disturbed, creating a mesmerizing blue glow in the water. This phenomenon is often referred to as \"sea sparkle\" and can be seen in coastal areas around the world.\n\nBioluminescence not only captivates our imagination but also has practical applications in science and medicine, including the development of biosensors and imaging techniques. It's a remarkable example of nature's creativity and complexity!",
          "sender": "Machine",
          "sender_name": "AI",
          "session_id": "chat-123",
          "timestamp": "2025-03-03T17:17:37+00:00",
          "flow_id": "d2bbd92b-187e-4c84-b2d4-5df365704201",
          "properties": {
            "source": {
              "id": "OpenAIModel-d1wOZ",
              "display_name": "OpenAI",
              "source": "gpt-4o-mini"
            },
            "icon": "OpenAI"
          },
          "component_id": "ChatOutput-ylMzN"
        }
      }
    }]
  }]
}
```
</details>

If you are parsing the response in an application, you most likely need to extract the relevant content from the response, rather than pass the entire response back to the user.
For an example of a script that extracts data from a Langflow API response, see the [Quickstart](/get-started-quickstart).

### Stream LLM token responses

With `/v1/run/$FLOW_ID`, the flow is executed as a batch with optional LLM token response streaming.

To stream LLM token responses, append the `?stream=true` query parameter to the request:

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true"

# Request payload
payload = {
    "message": "Tell me something interesting!",
    "session_id": "chat-123"
}

# Request headers
headers = {
    "accept": "application/json",
    "Content-Type": "application/json",
    "x-api-key": "LANGFLOW_API_KEY"
}

try:
    response = requests.post(url, json=payload, headers=headers, stream=True)
    response.raise_for_status()

    # Process streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
except requests.exceptions.RequestException as e:
    print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
  message: "Tell me something interesting!",
  session_id: "chat-123"
};

const options = {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'Content-Type': 'application/json',
    'x-api-key': 'LANGFLOW_API_KEY'
  },
  body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true', options)
  .then(async response => {
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    if (reader) {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        console.log(decoder.decode(value));
      }
    }
  })
  .catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
  "$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=true" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -d '{
    "message": "Tell me something interesting!",
    "session_id": "chat-123"
  }'
```

</TabItem>
</Tabs>

LLM chat responses are streamed back as `token` events, culminating in a final `end` event that closes the connection.

<details>
<summary>Result</summary>

The following example is truncated to illustrate a series of `token` events as well as the final `end` event that closes the LLM's token streaming response:

```text
{"event": "add_message", "data": {"timestamp": "2025-03-03T17:20:18", "sender": "User", "sender_name": "User", "session_id": "chat-123", "text": "Tell me about something interesting!", "files": [], "error": false, "edit": false, "properties": {"text_color": "", "background_color": "", "edited": false, "source": {"id": null, "display_name": null, "source": null}, "icon": "", "allow_markdown": false, "positive_feedback": null, "state": "complete", "targets": []}, "category": "message", "content_blocks": [], "id": "0103a21b-ebf7-4c02-9d72-017fb297f812", "flow_id": "d2bbd92b-187e-4c84-b2d4-5df365704201"}}

{"event": "add_message", "data": {"timestamp": "2025-03-03T17:20:18", "sender": "Machine", "sender_name": "AI", "session_id": "chat-123", "text": "", "files": [], "error": false, "edit": false, "properties": {"text_color": "", "background_color": "", "edited": false, "source": {"id": "OpenAIModel-d1wOZ", "display_name": "OpenAI", "source": "gpt-4o-mini"}, "icon": "OpenAI", "allow_markdown": false, "positive_feedback": null, "state": "complete", "targets": []}, "category": "message", "content_blocks": [], "id": "27b66789-e673-4c65-9e81-021752925161", "flow_id": "d2bbd92b-187e-4c84-b2d4-5df365704201"}}

{"event": "token", "data": {"chunk": " Have", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "token", "data": {"chunk": " you", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "token", "data": {"chunk": " ever", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "token", "data": {"chunk": " heard", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "token", "data": {"chunk": " of", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "token", "data": {"chunk": " the", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "token", "data": {"chunk": " phenomenon", "id": "27b66789-e673-4c65-9e81-021752925161", "timestamp": "2025-03-03 17:20:18 UTC"}}

{"event": "end", "data": {"result": {"session_id": "chat-123", "message": "Sure! Have you ever heard of the phenomenon known as \"bioluminescence\"?..."}}}
```

</details>

### Run endpoint headers

| Header | Info | Example |
|--------|------|---------|
| Content-Type | Required. Specifies the JSON format. | "application/json" |
| accept | Optional. Specifies the response format. Defaults to JSON if not specified. | "application/json" |
| x-api-key | Required. Your Langflow API key for authentication. Can be passed as a header or query parameter. | "sk-..." |
| `X-LANGFLOW-GLOBAL-VAR-*` | Optional. Pass global variables to the flow. Variable names are automatically converted to uppercase. These variables take precedence over OS environment variables and are only available during this specific request execution. | `"X-LANGFLOW-GLOBAL-VAR-API_KEY: sk-..."` |

### Run endpoint parameters

| Parameter | Type | Info |
|-----------|------|------|
| flow_id | UUID/string | Required. Part of URL: `/run/$FLOW_ID` |
| stream | Boolean | Optional. Query parameter: `/run/$FLOW_ID?stream=true` |
| input_value | string | Optional. JSON body field. Main input text/prompt. Default: `null` |
| input_type | string | Optional. JSON body field. Input type ("chat" or "text"). Default: `"chat"` |
| output_type | string | Optional. JSON body field. Output type ("chat", "any", "debug"). Default: `"chat"` |
| output_component | string | Optional. JSON body field. Target component for output. Default: `""` |
| tweaks | object | Optional. JSON body field. Component adjustments. Default: `null` |
| session_id | string | Optional. JSON body field. Conversation context ID. See [Session ID](/session-id). Default: `null` |

### Request example with all headers and parameters

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true"

# Request payload with tweaks
payload = {
    "input_value": "Tell me a story",
    "input_type": "chat",
    "output_type": "chat",
    "output_component": "chat_output",
    "session_id": "chat-123",
    "tweaks": {
        "component_id": {
            "parameter_name": "value"
        }
    }
}

# Request headers
headers = {
    "Content-Type": "application/json",
    "accept": "application/json",
    "x-api-key": "LANGFLOW_API_KEY"
}

try:
    response = requests.post(url, json=payload, headers=headers, stream=True)
    response.raise_for_status()

    # Process streaming response
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))
except requests.exceptions.RequestException as e:
    print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
  input_value: "Tell me a story",
  input_type: "chat",
  output_type: "chat",
  output_component: "chat_output",
  session_id: "chat-123",
  tweaks: {
    component_id: {
      parameter_name: "value"
    }
  }
};

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'accept': 'application/json',
    'x-api-key': 'LANGFLOW_API_KEY'
  },
  body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID?stream=true', options)
  .then(async response => {
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();

    if (reader) {
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        console.log(decoder.decode(value));
      }
    }
  })
  .catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
  "$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID?stream=true" \
  -H "Content-Type: application/json" \
  -H "accept: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -d '{
    "input_value": "Tell me a story",
    "input_type": "chat",
    "output_type": "chat",
    "output_component": "chat_output",
    "session_id": "chat-123",
    "tweaks": {
      "component_id": {
        "parameter_name": "value"
      }
    }
  }'
```

</TabItem>
</Tabs>

### Pass global variables in request headers {#pass-global-variables-in-headers}

You can pass global variables to your flow using HTTP headers with the format `X-LANGFLOW-GLOBAL-VAR-{VARIABLE_NAME}`.

Variables passed in headers take precedence over OS environment variables. If a variable is provided in both a header and an environment variable, the header value is used. Variables are only available during this specific request execution and aren't persisted.

Variable names are automatically converted to uppercase. For example, `X-LANGFLOW-GLOBAL-VAR-api-key` becomes `API_KEY` in your flow.

You don't need to create these variables in Langflow's Global Variables section first. Pass any variable name using this header format.

<Tabs>
<TabItem value="Python" label="Python" default>

```python
import requests

url = "http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID"

# Request payload
payload = {
    "input_value": "Tell me about something interesting!",
    "input_type": "chat",
    "output_type": "chat"
}

# Request headers with global variables
headers = {
    "Content-Type": "application/json",
    "x-api-key": "LANGFLOW_API_KEY",
    "X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY": "sk-...",
    "X-LANGFLOW-GLOBAL-VAR-USER_ID": "user123",
    "X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT": "production"
}

try:
    response = requests.post(url, json=payload, headers=headers)
    response.raise_for_status()
    print(response.json())
except requests.exceptions.RequestException as e:
    print(f"Error making API request: {e}")
```

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

```js
const payload = {
  input_value: "Tell me about something interesting!",
  input_type: "chat",
  output_type: "chat"
};

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'LANGFLOW_API_KEY',
    'X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY': 'sk-...',
    'X-LANGFLOW-GLOBAL-VAR-USER_ID': 'user123',
    'X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT': 'production'
  },
  body: JSON.stringify(payload)
};

fetch('http://LANGFLOW_SERVER_URL/api/v1/run/FLOW_ID', options)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(err => console.error(err));
```

</TabItem>
<TabItem value="curl" label="curl">

```bash
curl -X POST \
  "$LANGFLOW_SERVER_URL/api/v1/run/$FLOW_ID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -H "X-LANGFLOW-GLOBAL-VAR-OPENAI_API_KEY: sk-..." \
  -H "X-LANGFLOW-GLOBAL-VAR-USER_ID: user123" \
  -H "X-LANGFLOW-GLOBAL-VAR-ENVIRONMENT: production" \
  -d '{
    "input_value": "Tell me about something interesting!",
    "input_type": "chat",
    "output_type": "chat"
  }'
```

</TabItem>
</Tabs>

If your flow components reference variables that aren't provided in headers or your Langflow database, the flow fails by default. To avoid this, you can set `LANGFLOW_FALLBACK_TO_ENV_VAR=True` in your `.env` file, which allows the flow to use values from OS environment variables if they aren't otherwise specified.


## Webhook run flow

Use the `/webhook` endpoint to start a flow by sending an HTTP `POST` request.

:::tip
After you add a [**Webhook** component](/webhook) to a flow, open the [**API access** pane](/concepts-publish), and then click the **Webhook curl** tab to get an automatically generated `POST /webhook` request for your flow.
For more information, see [Trigger flows with webhooks](/webhook).
:::

```bash
curl -X POST \
  "$LANGFLOW_SERVER_URL/api/v1/webhook/$FLOW_ID" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -d '{"data": "example-data"}'
```

<details>
<summary>Result</summary>

```json
{
  "message": "Task started in the background",
  "status": "in progress"
}
```

</details>

## Deprecated flow trigger endpoints

The following endpoints are deprecated and replaced by the `/run` endpoint:

* `/process`
* `/predict`