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
TypeScript
curl


_20import requests
_20
_20url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
_20headers = {
_20    "Content-Type": "application/json",
_20    "x-api-key": LANGFLOW_API_KEY
_20}
_20
_20payload = {
_20    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_20    "background": False,
_20    "inputs": {
_20        "ChatInput-abc.input_type": "chat",
_20        "ChatInput-abc.input_value": "what is 2+2",
_20        "ChatInput-abc.session_id": "session-123"
_20    }
_20}
_20
_20response = requests.post(url, json=payload, headers=headers)
_20print(response.json())


_29import axios from 'axios';
_29
_29const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;
_29
_29const payload = {
_29  flow_id: "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_29  background: false,
_29  inputs: {
_29    "ChatInput-abc.input_type": "chat",
_29    "ChatInput-abc.input_value": "what is 2+2",
_29    "ChatInput-abc.session_id": "session-123"
_29  }
_29};
_29
_29const runWorkflow = async () => {
_29  try {
_29    const response = await axios.post(url, payload, {
_29      headers: {
_29        'Content-Type': 'application/json',
_29        'x-api-key': LANGFLOW_API_KEY
_29      }
_29    });
_29    console.log(response.data);
_29  } catch (error) {
_29    console.error('Error triggering workflow:', error);
_29  }
_29};
_29
_29runWorkflow();


_13curl -X POST \
_13  "$LANGFLOW_SERVER_URL/api/v2/workflows" \
_13  -H "Content-Type: application/json" \
_13  -H "x-api-key: $LANGFLOW_API_KEY" \
_13  -d '{
_13    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_13    "background": false,
_13    "inputs": {
_13      "ChatInput-abc.input_type": "chat",
_13      "ChatInput-abc.input_value": "what is 2+2",
_13      "ChatInput-abc.session_id": "session-123"
_13    }
_13  }'

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
TypeScript
curl


_21import requests
_21
_21url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
_21headers = {
_21    "Content-Type": "application/json",
_21    "x-api-key": LANGFLOW_API_KEY
_21}
_21
_21payload = {
_21    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_21    "background": True,
_21    "stream": False,
_21    "inputs": {
_21        "ChatInput-abc.input_type": "chat",
_21        "ChatInput-abc.input_value": "Process this in the background",
_21        "ChatInput-abc.session_id": "session-456"
_21    }
_21}
_21
_21response = requests.post(url, json=payload, headers=headers)
_21print(response.json())  # Returns job_id immediately


_30import axios from 'axios';
_30
_30const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;
_30
_30const payload = {
_30  flow_id: "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_30  background: true,
_30  stream: false,
_30  inputs: {
_30    "ChatInput-abc.input_type": "chat",
_30    "ChatInput-abc.input_value": "Process this in the background",
_30    "ChatInput-abc.session_id": "session-456"
_30  }
_30};
_30
_30const runWorkflow = async () => {
_30  try {
_30    const response = await axios.post(url, payload, {
_30      headers: {
_30        'Content-Type': 'application/json',
_30        'x-api-key': LANGFLOW_API_KEY
_30      }
_30    });
_30    console.log(response.data);  // Returns job_id immediately
_30  } catch (error) {
_30    console.error('Error triggering workflow:', error);
_30  }
_30};
_30
_30runWorkflow();


_14curl -X POST \
_14  "$LANGFLOW_SERVER_URL/api/v2/workflows" \
_14  -H "Content-Type: application/json" \
_14  -H "x-api-key: $LANGFLOW_API_KEY" \
_14  -d '{
_14    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
_14    "background": true,
_14    "stream": false,
_14    "inputs": {
_14      "ChatInput-abc.input_type": "chat",
_14      "ChatInput-abc.input_value": "Process this in the background",
_14      "ChatInput-abc.session_id": "session-456"
_14    }
_14  }'

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
TypeScript
curl


_13import requests
_13
_13url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
_13params = {
_13    "job_id": "job_id_1234567890"
_13}
_13headers = {
_13    "accept": "application/json",
_13    "x-api-key": LANGFLOW_API_KEY
_13}
_13
_13response = requests.get(url, params=params, headers=headers)
_13print(response.json())


_23import axios from 'axios';
_23
_23const jobId = 'job_id_1234567890';
_23const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;
_23
_23const getWorkflowStatus = async () => {
_23  try {
_23    const response = await axios.get(url, {
_23      params: {
_23        job_id: jobId
_23      },
_23      headers: {
_23        'accept': 'application/json',
_23        'x-api-key': LANGFLOW_API_KEY
_23      }
_23    });
_23    console.log(response.data);
_23  } catch (error) {
_23    console.error('Error getting workflow status:', error);
_23  }
_23};
_23
_23getWorkflowStatus();


_10curl -X GET \
_10  "$LANGFLOW_SERVER_URL/api/v2/workflows?job_id=job_id_1234567890" \
_10  -H "accept: application/json" \
_10  -H "x-api-key: $LANGFLOW_API_KEY"

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
TypeScript
curl


_13import requests
_13
_13url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows/stop"
_13headers = {
_13    "Content-Type": "application/json",
_13    "x-api-key": LANGFLOW_API_KEY
_13}
_13payload = {
_13    "job_id": "job_id_1234567890"
_13}
_13
_13response = requests.post(url, json=payload, headers=headers)
_13print(response.json())


_23import axios from 'axios';
_23
_23const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows/stop`;
_23
_23const payload = {
_23  job_id: "job_id_1234567890"
_23};
_23
_23const stopWorkflow = async () => {
_23  try {
_23    const response = await axios.post(url, payload, {
_23      headers: {
_23        'Content-Type': 'application/json',
_23        'x-api-key': LANGFLOW_API_KEY
_23      }
_23    });
_23    console.log(response.data);
_23  } catch (error) {
_23    console.error('Error stopping workflow:', error);
_23  }
_23};
_23
_23stopWorkflow();


_10curl -X POST \
_10  "$LANGFLOW_SERVER_URL/api/v2/workflows/stop" \
_10  -H "Content-Type: application/json" \
_10  -H "x-api-key: $LANGFLOW_API_KEY" \
_10  -d '{
_10    "job_id": "job_id_1234567890"
_10  }'

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