Version: 1.10.x (Next)

Workflow API (Beta)

Beta Feature

The Workflow API is currently in Beta. The API endpoints and response formats may change in future releases.

The Workflow API provides programmatic access to execute Langflow workflows synchronously or asynchronously. Synchronous requests receive complete results immediately upon completion. Asynchronous requests are queued in the background and will run until complete, or a request is issued to the Stop Workflow endpoint.

The Workflow API is part of the Langflow Developer v2 API and offers enhanced workflow execution capabilities compared to the v1 /run endpoint.

Prerequisites

Before using the API, you need:

Install and start Langflow with the developer API enabled

The Workflows API endpoints require the developer_api_enabled setting to be enabled. If this setting is disabled, these endpoints will return a 404 Not Found error.

To enable the developer API endpoint, do the following:
1. In the Langflow .env file, set the environment variable to true:
  _10LANGFLOW_DEVELOPER_API_ENABLED=true
2. Start your Langflow server with the .env file enabled:
  _10uv run langflow run --env-file .env
For more information about configuring environment variables, see Environment variables.
Create a Langflow API key
Create a flow that you want to execute
Get the flow ID or endpoint name of the flow you want to execute

Set environment variables

All code examples in this documentation assume you have set the following environment variables:

Python:


_10import os
_10
_10LANGFLOW_SERVER_URL = os.getenv("LANGFLOW_SERVER_URL")
_10LANGFLOW_API_KEY = os.getenv("LANGFLOW_API_KEY")

TypeScript/JavaScript:


_10const LANGFLOW_SERVER_URL = process.env.LANGFLOW_SERVER_URL;
_10const LANGFLOW_API_KEY = process.env.LANGFLOW_API_KEY;

Set these environment variables before running the examples, or replace the variable references in the code examples with your actual Langflow server URL and API key.

The default LANGFLOW_SERVER_URL for a local Langflow deployment is http://localhost:7860. For remote deployments, the domain is set by your hosting service, such as https://UUID.ngrok.app.

Authentication and headers

All Workflows API requests require authentication using a Langflow API key. The API key is passed in the x-api-key header.

For more information, see Create a Langflow API key.

Header	Description	Example
`Content-Type`	Specifies the JSON format.	`application/json`
`x-api-key`	Your Langflow API key.	`sk-...`
`accept`	Optional. Specifies the response format.	`application/json`

Execute workflows endpoint (synchronous or asynchronous)

Endpoint:


_10POST /api/v2/workflows

Description: Execute a workflow synchronously and receive complete results immediately upon completion. Set background=false to make the request synchronous.

Example synchronous request

Execute a workflow synchronously and receive complete results immediately:

Python
JavaScript
curl

1import os
2
3import requests
4
5base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
6flow_id = os.environ.get("FLOW_ID", "")
7api_key = os.environ.get("LANGFLOW_API_KEY", "")
8
9headers = {"Content-Type": "application/json", "x-api-key": api_key}
10
11payload = {
12    "flow_id": flow_id,
13    "background": False,
14    "stream": False,
15    "inputs": {},
16}
17
18response = requests.post(f"{base}/api/v2/workflows", headers=headers, json=payload, timeout=120)
19response.raise_for_status()
20print(response.text)
21

1const url = `${process.env.LANGFLOW_SERVER_URL ?? ""}/api/v2/workflows`;
2
3const options = {
4  method: 'POST',
5  headers: {
6    "Content-Type": `application/json`,
7    "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`,
8  },
9  body: JSON.stringify({
10  "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
11  "background": false,
12  "inputs": {
13    "ChatInput-abc.input_type": "chat",
14    "ChatInput-abc.input_value": "what is 2+2",
15    "ChatInput-abc.session_id": "session-123"
16  }
17}),
18};
19
20fetch(url, options)
21  .then(async (response) => {
22    if (!response.ok) {
23      throw new Error(`HTTP ${response.status}`);
24    }
25    const text = await response.text();
26    console.log(text);
27  })
28  .catch((error) => console.error(error));
29

1curl -X POST \
2  "$LANGFLOW_SERVER_URL/api/v2/workflows" \
3  -H "Content-Type: application/json" \
4  -H "x-api-key: $LANGFLOW_API_KEY" \
5  -d '{
6    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
7    "background": false,
8    "inputs": {
9      "ChatInput-abc.input_type": "chat",
10      "ChatInput-abc.input_value": "what is 2+2",
11      "ChatInput-abc.session_id": "session-123"
12    }
13  }'
14

Example asynchronous request

For long-running workflows, set background=true to get a job_id immediately, and then poll the status using the GET endpoint until the job is complete.

To stop a job, send a POST request to the Stop workflow endpoint.

tip

The asynchronous request contains stream parameter, but streaming is not yet supported. The parameter is included for future compatibility.

Example request:

Python
JavaScript
curl

1import os
2
3import requests
4
5base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
6flow_id = os.environ.get("FLOW_ID", "")
7api_key = os.environ.get("LANGFLOW_API_KEY", "")
8
9headers = {"Content-Type": "application/json", "x-api-key": api_key}
10
11payload = {
12    "flow_id": flow_id,
13    "background": True,
14    "stream": False,
15    "inputs": {},
16}
17
18response = requests.post(f"{base}/api/v2/workflows", headers=headers, json=payload, timeout=60)
19response.raise_for_status()
20print(response.text)
21

1const url = `${process.env.LANGFLOW_SERVER_URL ?? ""}/api/v2/workflows`;
2
3const options = {
4  method: 'POST',
5  headers: {
6    "Content-Type": `application/json`,
7    "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`,
8  },
9  body: JSON.stringify({
10  "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
11  "background": true,
12  "stream": false,
13  "inputs": {
14    "ChatInput-abc.input_type": "chat",
15    "ChatInput-abc.input_value": "Process this in the background",
16    "ChatInput-abc.session_id": "session-456"
17  }
18}),
19};
20
21fetch(url, options)
22  .then(async (response) => {
23    if (!response.ok) {
24      throw new Error(`HTTP ${response.status}`);
25    }
26    const text = await response.text();
27    console.log(text);
28  })
29  .catch((error) => console.error(error));
30

1curl -X POST \
2  "$LANGFLOW_SERVER_URL/api/v2/workflows" \
3  -H "Content-Type: application/json" \
4  -H "x-api-key: $LANGFLOW_API_KEY" \
5  -d '{
6    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
7    "background": true,
8    "stream": false,
9    "inputs": {
10      "ChatInput-abc.input_type": "chat",
11      "ChatInput-abc.input_value": "Process this in the background",
12      "ChatInput-abc.session_id": "session-456"
13    }
14  }'
15

Response:


_10{
_10  "job_id": "job_id_1234567890",
_10  "created_timestamp": "2025-01-15T10:30:00Z",
_10  "status": "queued",
_10  "errors": []
_10}

Request body

Field	Type	Required	Default	Description
`flow_id`	`string`	Yes	-	The ID or endpoint name of the flow to execute.
`flow_version`	`string`	No	-	Optional version hash to pin to a specific flow version.
`background`	`boolean`	No	`false`	Must be `false` for synchronous execution.
`inputs`	`object`	No	`{}`	Inputs for the workflow execution. Uses component identifiers with dot notation (e.g., `ChatInput-abc.input_value`). See Component identifiers and input structure for detailed information.

Example response


_22{
_22  "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_22  "job_id": "job_id_1234567890",
_22  "object": "response",
_22  "created_at": 1741476542,
_22  "status": "completed",
_22  "errors": [],
_22  "inputs": {
_22    "ChatInput-abc.input_type": "chat",
_22    "ChatInput-abc.input_value": "what is 2+2",
_22    "ChatInput-abc.session_id": "session-123"
_22  },
_22  "outputs": {
_22    "ChatOutput-xyz": {
_22      "type": "message",
_22      "component_id": "ChatOutput-xyz",
_22      "status": "completed",
_22      "content": "2 + 2 equals 4."
_22    }
_22  },
_22  "metadata": {}
_22}

Response body

The response includes an outputs field containing component-level results. Each output has a type field indicating the type of content:

Type	Description	Example
`message`	Text message content.	Chat responses, summaries
`image`	Image URL or data.	Generated images, processed images
`sql`	SQL query results.	Database query outputs
`data`	Structured data.	JSON objects, arrays
`file`	File reference.	Generated documents, reports

Get workflow status endpoint

Endpoint: GET /api/v2/workflows

Description: Retrieve the status and results of a workflow execution by job ID.

Example request

Python
JavaScript
curl

1import os
2
3import requests
4
5base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
6flow_id = os.environ.get("FLOW_ID", "")
7api_key = os.environ.get("LANGFLOW_API_KEY", "")
8
9headers = {"Content-Type": "application/json", "x-api-key": api_key}
10
11start = requests.post(
12    f"{base}/api/v2/workflows",
13    headers=headers,
14    json={"flow_id": flow_id, "background": True, "stream": False, "inputs": {}},
15    timeout=60,
16)
17start.raise_for_status()
18print(start.text)
19

1const url = `${process.env.LANGFLOW_SERVER_URL ?? ""}/api/v2/workflows?job_id=job_id_1234567890`;
2
3const options = {
4  method: 'GET',
5  headers: {
6    "accept": `application/json`,
7    "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`,
8  },
9};
10
11fetch(url, options)
12  .then(async (response) => {
13    if (!response.ok) {
14      throw new Error(`HTTP ${response.status}`);
15    }
16    const text = await response.text();
17    console.log(text);
18  })
19  .catch((error) => console.error(error));
20

1curl -X GET \
2  "$LANGFLOW_SERVER_URL/api/v2/workflows?job_id=job_id_1234567890" \
3  -H "accept: application/json" \
4  -H "x-api-key: $LANGFLOW_API_KEY"
5

Query parameters

Parameter	Type	Required	Description
`job_id`	`string`	Yes	The job ID returned from a workflow execution.
`stream`	`boolean`	No	If `true`, returns server-sent events stream. Default: `false`.
`sequence_id`	`integer`	No	Optional sequence ID to resume streaming from a specific point.

Example response


_24{
_24  "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_24  "job_id": "job_id_1234567890",
_24  "object": "response",
_24  "created_at": 1741476542,
_24  "status": "completed",
_24  "errors": [],
_24  "outputs": {
_24    "ChatOutput-xyz": {
_24      "type": "message",
_24      "component_id": "ChatOutput-xyz",
_24      "status": "completed",
_24      "content": "Processing complete..."
_24    }
_24  },
_24  "input": [
_24    {
_24      "type": "text",
_24      "data": "Input text prompt for the workflow execution",
_24      "role": "User"
_24    }
_24  ],
_24  "metadata": {}
_24}

Response body

The response includes a status field that indicates the current state of the workflow execution:

Status	Description
`queued`	Job is queued and waiting to start.
`in_progress`	Job is currently executing.
`completed`	Job completed successfully.
`failed`	Job failed during execution.
`error`	Job encountered an error.

Stop workflow endpoint

Endpoint: POST /api/v2/workflows/stop

Description: Stop a running workflow execution by job ID.

Example request

Python
JavaScript
curl

1import os
2
3import requests
4
5base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
6flow_id = os.environ.get("FLOW_ID", "")
7api_key = os.environ.get("LANGFLOW_API_KEY", "")
8
9headers = {"Content-Type": "application/json", "x-api-key": api_key}
10
11start = requests.post(
12    f"{base}/api/v2/workflows",
13    headers=headers,
14    json={"flow_id": flow_id, "background": True, "stream": False, "inputs": {}},
15    timeout=60,
16)
17start.raise_for_status()
18job_id = start.json()["job_id"]
19
20stop = requests.post(
21    f"{base}/api/v2/workflows/stop",
22    headers=headers,
23    json={"job_id": job_id},
24    timeout=60,
25)
26print(stop.status_code, stop.text)
27

1const url = `${process.env.LANGFLOW_SERVER_URL ?? ""}/api/v2/workflows/stop`;
2
3const options = {
4  method: 'POST',
5  headers: {
6    "Content-Type": `application/json`,
7    "x-api-key": `${process.env.LANGFLOW_API_KEY ?? ""}`,
8  },
9  body: JSON.stringify({
10  "job_id": "job_id_1234567890"
11}),
12};
13
14fetch(url, options)
15  .then(async (response) => {
16    if (!response.ok) {
17      throw new Error(`HTTP ${response.status}`);
18    }
19    const text = await response.text();
20    console.log(text);
21  })
22  .catch((error) => console.error(error));
23

1curl -X POST \
2  "$LANGFLOW_SERVER_URL/api/v2/workflows/stop" \
3  -H "Content-Type: application/json" \
4  -H "x-api-key: $LANGFLOW_API_KEY" \
5  -d '{
6    "job_id": "job_id_1234567890"
7  }'
8

Request body

Field	Type	Required	Default	Description
`job_id`	`string`	Yes	-	The job ID of the workflow to stop.

Example response


_10{
_10  "job_id": "job_id_1234567890",
_10  "message": "Job job_id_1234567890 cancelled successfully."
_10}

Component identifiers and input structure

The Workflows API uses component identifiers with dot notation to specify inputs for individual components in your workflow. This allows you to pass values to specific components and override component parameters.

Component identifiers use the format {component_id}.{parameter_name}. When making requests to the Workflows API, include component identifiers in the inputs object. For example, this demonstrates targeting multiple components and their parameters in a single request.


_11{
_11  "flow_id": "your-flow-id",
_11  "inputs": {
_11    "ChatInput-abc.input_type": "chat",
_11    "ChatInput-abc.input_value": "what is 2+2",
_11    "ChatInput-abc.session_id": "session-123",
_11    "OpenSearchComponent-xyz.opensearch_url": "https://opensearch:9200",
_11    "LLMComponent-123.temperature": 0.7,
_11    "LLMComponent-123.max_tokens": 100
_11  }
_11}

To find the component ID in the Langflow UI, open your flow in Langflow, click the component, and then click Controls. The component ID is at the top of the Controls pane.

You can override any component's parameters.

Error handling

The API uses standard HTTP status codes to indicate success or failure:

Status Code	Description
`200 OK`	Request successful.
`400 Bad Request`	Invalid request parameters.
`401 Unauthorized`	Invalid or missing API key.
`404 Not Found`	Flow not found or developer API disabled.
`500 Internal Server Error`	Server error during execution.
`501 Not Implemented`	Endpoint not yet implemented.

Error response format


_10{
_10  "detail": "Error message describing what went wrong"
_10}

Prerequisites​

Set environment variables​

Authentication and headers​

Execute workflows endpoint (synchronous or asynchronous)​

Example synchronous request​

Example asynchronous request​

Request body​

Example response​

Response body​

Get workflow status endpoint​

Example request​

Query parameters​

Example response​

Response body​

Stop workflow endpoint​

Example request​

Request body​

Example response​

Component identifiers and input structure​

Error handling​

Error response format​

Prerequisites

Set environment variables

Authentication and headers

Execute workflows endpoint (synchronous or asynchronous)

Example synchronous request

Example asynchronous request

Request body

Example response

Response body

Get workflow status endpoint

Example request

Query parameters

Example response

Response body

Stop workflow endpoint

Example request

Request body

Example response

Component identifiers and input structure

Error handling

Error response format