Workflow API (Beta)

import CodeBlock from '@theme/CodeBlock'; 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 exampleWorkflowsApiExampleStreamLangflowRequest from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-stream-langflow-request.sh'; import examplePythonWorkflowsApiExampleStreamLangflowRequest from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-stream-langflow-request.py'; import exampleJavascriptWorkflowsApiExampleStreamLangflowRequest from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-stream-langflow-request.js'; import exampleWorkflowsApiExampleStreamAguiRequest from '!!raw-loader!@site/docs/API-Reference/curl-examples/workflows-api/example-stream-agui-request.sh'; import examplePythonWorkflowsApiExampleStreamAguiRequest from '!!raw-loader!@site/docs/API-Reference/python-examples/workflows-api/example-stream-agui-request.py'; import exampleJavascriptWorkflowsApiExampleStreamAguiRequest from '!!raw-loader!@site/docs/API-Reference/javascript-examples/workflows-api/example-stream-agui-request.js';

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import Icon from "@site/src/components/icon"; 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 in sync, stream, or background modes.

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

As of Langflow version 1.11, stream mode supports both Langflow's built-in EventManager and the AG-UI protocol.

:::tip New to the Workflow API? Start with the Workflow API quickstart for a step-by-step walkthrough of sync, stream, and background modes. :::

Execute workflow endpoint

Endpoint:

POST /api/v2/workflows

Description: Execute a workflow in sync, stream, or background mode.

Request body

Execute flow in sync mode

Set "mode": "sync" or omit mode to run inline and receive the full response when execution completes.

<CodeBlock language="python">{examplePythonWorkflowsApiExampleSynchronousRequest}</CodeBlock>

<CodeBlock language="javascript">{exampleJavascriptWorkflowsApiExampleSynchronousRequest}</CodeBlock>

<CodeBlock language="bash">{exampleWorkflowsApiExampleSynchronousRequest}</CodeBlock>

Execute flow with selected stream mode {#execute-flow-with-selected-stream-mode}

Set "mode": "stream" to receive a Server-Sent Events (SSE) stream for the run.

stream_protocol is set to langflow by default, which emits the built-in Langflow EventManager output. For more information, see Stream with Langflow EventManager

Set stream_protocol to agui to emit events using the AG-UI protocol instead. For more information, see Stream with AG-UI.

If stream_protocol names an unknown adapter, the endpoint returns 422 with an available list of registered protocol names.

Stream with Langflow EventManager {#stream-with-langflow}

stream_protocol defaults to langflow, which passes through the built-in Langflow EventManager events. Each SSE frame has a monotonic id: and a data: line containing JSON shaped like {"event": "<type>", "data": {...}}. This is the same wire format the v1 build stream uses, so existing Langflow clients can read it without changes.

Omit stream_protocol or set it explicitly to "langflow". Use curl -N so the client does not buffer the stream.

<CodeBlock language="python">{examplePythonWorkflowsApiExampleStreamLangflowRequest}</CodeBlock>

<CodeBlock language="javascript">{exampleJavascriptWorkflowsApiExampleStreamLangflowRequest}</CodeBlock>

<CodeBlock language="bash">{exampleWorkflowsApiExampleStreamLangflowRequest}</CodeBlock>

Common EventManager event types:

For more examples of token and add_message events, see Stream LLM token responses.

Stream with AG-UI {#stream-with-ag-ui}

Stream with the AG-UI protocol when your client expects agent lifecycle events such as RUN_STARTED and TEXT_MESSAGE_* instead of Langflow's internal events. Read responses as an SSE stream. Each data: line contains one AG-UI event serialized as JSON. Close flow runs when you receive RUN_FINISHED, or handle failures on RUN_ERROR.

Send POST /api/v2/workflows with "mode": "stream" and "stream_protocol": "agui".

<CodeBlock language="python">{examplePythonWorkflowsApiExampleStreamAguiRequest}</CodeBlock>

<CodeBlock language="javascript">{exampleJavascriptWorkflowsApiExampleStreamAguiRequest}</CodeBlock>

<CodeBlock language="bash">{exampleWorkflowsApiExampleStreamAguiRequest}</CodeBlock>

Common AG-UI event types:

Langflow also emits CUSTOM events that generic AG-UI clients can ignore, such as langflow.log, langflow.content.*, langflow.message.removed, and langflow.run.cancelled.

For the full AG-UI event catalog, see the AG-UI specification.

For a longer client example that parses AG-UI frames and chains two runs in one session_id, see example-stream-agui-parse.py (and matching .js / .sh files) under docs/docs/API-Reference/.

Execute flow in background mode

Set "mode": "background" to queue a job and receive a job_id immediately. Poll GET /api/v2/workflows for status and results, re-attach to the event stream with GET /api/v2/workflows/{job_id}/events, or stop the job with POST /api/v2/workflows/stop.

Background runs honor the stream_protocol selected when the job was created.

<CodeBlock language="python">{examplePythonWorkflowsApiExampleAsynchronousRequest}</CodeBlock>

<CodeBlock language="javascript">{exampleJavascriptWorkflowsApiExampleAsynchronousRequest}</CodeBlock>

<CodeBlock language="bash">{exampleWorkflowsApiExampleAsynchronousRequest}</CodeBlock>

See Background response fields in Response body for the job object returned when you queue a background run.

Re-attach to a background run {#re-attach-to-a-background-run}

Endpoint: GET /api/v2/workflows/{job_id}/events (also returned as links.events on the background job response)

You can replay buffered SSE events from a background run and tail the stream until the job finishes.

Each SSE frame includes an id: line. Pass the last id value you received in a Last-Event-ID header to resume from the next event.

headers = {
    "x-api-key": api_key,
    "Accept": "text/event-stream",
    "Last-Event-ID": last_event_id,
}

Response body {#response-body}

The response shape depends on the selected mode.

stream mode returns Server Sent Events. For more information, see Execute flow with selected stream mode.

sync mode returns a completed WorkflowExecutionResponse, for example:

{
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "session_id": "session-123",
  "job_id": "a98d9753-9259-47ca-9783-69a9d8d26889",
  "object": "response",
  "created_timestamp": "2026-06-30T16:00:56.917538+00:00",
  "status": "completed",
  "output": {
    "reason": "single",
    "text": "2 + 2 equals 4.",
    "source": "ChatOutput-xyz"
  },
  "has_errors": false,
  "errors": [],
  "inputs": {},
  "globals": {
    "FILENAME": "relatório—final.pdf",
    "OWNER_NAME": "José"
  },
  "outputs": {
    "ChatOutput-xyz": {
      "type": "message",
      "status": "completed",
      "display_name": "Chat Output",
      "content": "2 + 2 equals 4."
    }
  }
}

Sync response fields

Each value in outputs includes:

Background response fields {#background-response-fields}

background mode returns a job object immediately (object: "job"). Poll GET /api/v2/workflows until the job completes; the completed result uses the same WorkflowExecutionResponse shape as sync mode (see the example above).

{
  "job_id": "a98d9753-9259-47ca-9783-69a9d8d26889",
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "object": "job",
  "created_timestamp": "2026-06-30T16:00:56.917538+00:00",
  "status": "queued",
  "links": {
    "status": "/api/v2/workflows?job_id=a98d9753-9259-47ca-9783-69a9d8d26889",
    "events": "/api/v2/workflows/a98d9753-9259-47ca-9783-69a9d8d26889/events",
    "stop": "/api/v2/workflows/stop"
  },
  "errors": [],
  "globals": {}
}

Get workflow status endpoint {#get-workflow-status-endpoint}

Endpoint: GET /api/v2/workflows

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

Example request

<CodeBlock language="python">{examplePythonWorkflowsApiExampleRequest}</CodeBlock>

<CodeBlock language="javascript">{exampleJavascriptWorkflowsApiExampleRequest}</CodeBlock>

<CodeBlock language="bash">{exampleWorkflowsApiExampleRequest}</CodeBlock>

Query parameters

Example response

{
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "session_id": "session-123",
  "job_id": "a98d9753-9259-47ca-9783-69a9d8d26889",
  "object": "response",
  "created_timestamp": "2026-06-30T16:00:56.917538+00:00",
  "status": "completed",
  "output": {
    "reason": "single",
    "text": "Processing complete...",
    "source": "ChatOutput-xyz"
  },
  "has_errors": false,
  "errors": [],
  "inputs": {},
  "globals": {},
  "outputs": {
    "ChatOutput-xyz": {
      "type": "message",
      "status": "completed",
      "display_name": "Chat Output",
      "content": "Processing complete..."
    }
  }
}

Response body

Returns one of two JSON schemas depending on job state:

When the job is still active, poll GET /api/v2/workflows?job_id=… or re-attach to events for live output.

The status values are:

Stop workflow endpoint {#stop-workflow-endpoint}

Endpoint: POST /api/v2/workflows/stop

Description: Stop a running workflow execution by job ID.

Example request

<CodeBlock language="python">{examplePythonWorkflowsApiExampleRequest2}</CodeBlock>

<CodeBlock language="javascript">{exampleJavascriptWorkflowsApiExampleRequest2}</CodeBlock>

<CodeBlock language="bash">{exampleWorkflowsApiExampleRequest2}</CodeBlock>

Request body

Example response

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

Pass request-level global variables {#request-level-global-variables}

Pass request-scoped variables in the globals JSON field. They are available to workflow components for the duration of the run.

Use globals when values are large, shared across runs, or would exceed HTTP header size limits. Tweaks are better suited for one-off component overrides. globals is keyed by variable name and not component ID, so it stays stable when the UI regenerates node IDs when importing flows.

globals is honored in sync mode only; stream and background runs ignore it. The Workflow API is in Beta, and this transport may continue to evolve.

Use a stable name in the UI and then pass it in globals

To avoid depending on changing component IDs, rename a component, create a matching global variable, bind the field, and pass the value in the request.

1. To rename the component in the UI, click <Icon name="PencilLine" aria-hidden="true"/> Edit, and then rename the component. This example uses CUSTOMER_PROMPT.
2. Save the flow.
3. Create a new global variable with the same name as the component, such as CUSTOMER_PROMPT, and save it. For more about creating global variables, see Global variables.
4. In the field you want to fill at runtime, click the <Icon name="Globe" aria-hidden="true"/> Globe icon, select CUSTOMER_PROMPT, and save the flow.
5. Call the v2 Workflow API in sync mode and pass the value in globals.

curl -X POST "http://localhost:7860/api/v2/workflows" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "flow_id": "YOUR_FLOW_ID",
    "mode": "sync",
    "input_value": "hello",
    "globals": {
      "CUSTOMER_PROMPT": "The prompt with many words..."
    }
  }'

If you integrated against an earlier Workflow API preview, X-LANGFLOW-GLOBAL-VAR-* headers still work for sync runs on POST /api/v2/workflows. The server merges them with body globals; when the same key is sent both ways, the body value wins.

Prefer the globals body field for new integrations. Header-based globals may be removed in a future release.

This note applies to the Workflow API only. The v1 /run and /responses endpoints still document X-LANGFLOW-GLOBAL-VAR-* headers as their normal transport for request-level variables.

Component tweaks {#component-tweaks}

Use the tweaks object for one-off component parameter overrides in a single run. Keys are component ids; values are objects of field names and values to set on that component.

{
  "flow_id": "67ccd2be-17f0-8190-81ff-3bb2cf6508e6",
  "input_value": "what is 2+2",
  "tweaks": {
    "LLMComponent-123": {
      "temperature": 0.7,
      "max_tokens": 100
    }
  }
}

For exposing fields in generated API snippets and related UI steps, see Tweaks (API inputs). For large or stable values that should not depend on component ids, prefer request-level global variables.

Error handling

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

Error response format

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

For an unknown stream_protocol, the 422 response includes an available list of registered protocol names (langflow, agui).

See also

• Workflow API quickstart — run a flow in sync, stream, and background modes with copy-paste examples.