langflow/docs/versioned_docs/version-1.10.0/API-Reference/workflows-api.mdx

---
title: Workflow API (Beta)
slug: /workflow-api
---
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 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](#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.

<PartialAPISetup />

## 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:

<Tabs>
<TabItem value="Python" label="Python" default>

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

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

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

</TabItem>
<TabItem value="curl" label="curl">

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

</TabItem>
</Tabs>

### 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](#get-workflow-status-endpoint) until the job is complete.

To stop a job, send a POST request to the [Stop workflow endpoint](#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:**

<Tabs>
<TabItem value="Python" label="Python" default>

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

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

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

</TabItem>
<TabItem value="curl" label="curl">

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

</TabItem>
</Tabs>

**Response:**

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

### 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](#component-identifiers-and-input-structure) for detailed information. |
| `globals` | `object` | No | `{}` | Request-level global variables available to workflow components. Use this body field for arbitrary strings, including Unicode values. Keys are limited to 256 characters and values to 64 KB. See [Migrating from `X-LANGFLOW-GLOBAL-VAR-*` headers](#migrating-from-x-langflow-global-var--headers). |

### Example response

```json
{
  "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:

| 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

<Tabs>
<TabItem value="Python" label="Python" default>

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

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

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

</TabItem>
<TabItem value="curl" label="curl">

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

</TabItem>
</Tabs>

### 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

```json
{
  "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:

| 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

<Tabs>
<TabItem value="Python" label="Python" default>

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

</TabItem>
<TabItem value="JavaScript" label="JavaScript">

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

</TabItem>
<TabItem value="curl" label="curl">

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

</TabItem>
</Tabs>

### Request body

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

### Example response

```json
{
  "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):**

```bash
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:**

```bash
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.

```json
{
  "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:

| 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

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