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"
  },
  "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."
}

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"
}