Workflow API (Beta)

import CodeSnippet from '@site/src/components/CodeSnippet'; import exampleWorkflowsApiExampleSynchronousRequest from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-synchronous-request.sh'; import exampleWorkflowsApiExampleAsynchronousRequest from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-asynchronous-request.sh'; import exampleWorkflowsApiExampleRequest from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-request.sh'; import exampleWorkflowsApiExampleRequest2 from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-request-2.sh'; import examplePythonWorkflowsApiExampleSynchronousRequest from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-synchronous-request.py'; import examplePythonWorkflowsApiExampleAsynchronousRequest from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-asynchronous-request.py'; import examplePythonWorkflowsApiExampleRequest from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-request.py'; import examplePythonWorkflowsApiExampleRequest2 from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-request-2.py'; import exampleJavascriptWorkflowsApiExampleSynchronousRequest from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-synchronous-request.js'; import exampleJavascriptWorkflowsApiExampleAsynchronousRequest from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-asynchronous-request.js'; import exampleJavascriptWorkflowsApiExampleRequest from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-request.js'; import exampleJavascriptWorkflowsApiExampleRequest2 from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-request-2.js';

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import PartialAPISetup from '@site/docs/_partial-api-setup.mdx';

:::warning 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.

Execute workflows endpoint (synchronous or asynchronous)

Endpoint:

POST /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:

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:

Response:

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

Request body

Example response

{
  "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
  "job_id": "job_id_1234567890",
  "object": "response",
  "created_at": 1741476542,
  "status": "completed",
  "errors": [],
  "inputs": {
    "ChatInput-abc.input_type": "chat",
    "ChatInput-abc.input_value": "what is 2+2",
    "ChatInput-abc.session_id": "session-123"
  },
  "globals": {
    "FILENAME": "relatório—final.pdf",
    "OWNER_NAME": "José"
  },
  "outputs": {
    "ChatOutput-xyz": {
      "type": "message",
      "component_id": "ChatOutput-xyz",
      "status": "completed",
      "content": "2 + 2 equals 4."
    }
  },
  "metadata": {}
}

Response body

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

Get workflow status endpoint

Endpoint: GET /api/v2/workflows

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

Example request

Query parameters

Example response

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

Response body

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

Stop workflow endpoint

Endpoint: POST /api/v2/workflows/stop

Description: Stop a running workflow execution by job ID.

Example request

Request body

Example response

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

Migrating from X-LANGFLOW-GLOBAL-VAR-* headers

Earlier preview releases of the Workflow API accepted request-level global variables via X-LANGFLOW-GLOBAL-VAR-* HTTP headers. HTTP headers cannot reliably carry arbitrary Unicode values, so the v2 Workflow API now accepts globals as a typed globals field in the JSON request body.

For backwards compatibility, the previous header transport is still honored for one release:

• Body globals always win when the same key is sent both ways.
• A deprecation warning is logged on every request that carries X-LANGFLOW-GLOBAL-VAR-* headers.
• Header-based globals will be removed in a future Langflow release. Migrate to the globals body field at your earliest convenience.

Before (deprecated):

curl -X POST "$LANGFLOW_URL/api/v2/workflows" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-LANGFLOW-GLOBAL-VAR-FILENAME: relatorio-final.pdf" \
  -H "X-LANGFLOW-GLOBAL-VAR-OWNER_NAME: Jose" \
  --data '{"flow_id": "..."}'

After:

curl -X POST "$LANGFLOW_URL/api/v2/workflows" \
  -H "x-api-key: $LANGFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "flow_id": "...",
    "globals": {
      "FILENAME": "relatório—final.pdf",
      "OWNER_NAME": "José"
    }
  }'

Keys may use the same characters supported by the global variables panel in the Langflow UI; they are bounded to 256 characters, and values are bounded to 64 KB.

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.

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

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:

Error response format

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