langflow/docs/docs/API-Reference/workflows-api.mdx

---
title: Workflow API (Beta)
slug: /workflow-api
---

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>

```python
import requests

url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
headers = {
    "Content-Type": "application/json",
    "x-api-key": LANGFLOW_API_KEY
}

payload = {
    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
    "background": False,
    "inputs": {
        "ChatInput-abc.input_type": "chat",
        "ChatInput-abc.input_value": "what is 2+2",
        "ChatInput-abc.session_id": "session-123"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

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

```typescript
import axios from 'axios';

const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;

const payload = {
  flow_id: "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
  background: false,
  inputs: {
    "ChatInput-abc.input_type": "chat",
    "ChatInput-abc.input_value": "what is 2+2",
    "ChatInput-abc.session_id": "session-123"
  }
};

const runWorkflow = async () => {
  try {
    const response = await axios.post(url, payload, {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': LANGFLOW_API_KEY
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error triggering workflow:', error);
  }
};

runWorkflow();
```

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

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

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

```python
import requests

url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
headers = {
    "Content-Type": "application/json",
    "x-api-key": LANGFLOW_API_KEY
}

payload = {
    "flow_id": "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
    "background": True,
    "stream": False,
    "inputs": {
        "ChatInput-abc.input_type": "chat",
        "ChatInput-abc.input_value": "Process this in the background",
        "ChatInput-abc.session_id": "session-456"
    }
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())  # Returns job_id immediately
```

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

```typescript
import axios from 'axios';

const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;

const payload = {
  flow_id: "flow_67ccd2be17f0819081ff3bb2cf6508e60bb6a6b452d3795b",
  background: true,
  stream: false,
  inputs: {
    "ChatInput-abc.input_type": "chat",
    "ChatInput-abc.input_value": "Process this in the background",
    "ChatInput-abc.session_id": "session-456"
  }
};

const runWorkflow = async () => {
  try {
    const response = await axios.post(url, payload, {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': LANGFLOW_API_KEY
      }
    });
    console.log(response.data);  // Returns job_id immediately
  } catch (error) {
    console.error('Error triggering workflow:', error);
  }
};

runWorkflow();
```

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

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

</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. |

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

```python
import requests

url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows"
params = {
    "job_id": "job_id_1234567890"
}
headers = {
    "accept": "application/json",
    "x-api-key": LANGFLOW_API_KEY
}

response = requests.get(url, params=params, headers=headers)
print(response.json())
```

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

```typescript
import axios from 'axios';

const jobId = 'job_id_1234567890';
const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows`;

const getWorkflowStatus = async () => {
  try {
    const response = await axios.get(url, {
      params: {
        job_id: jobId
      },
      headers: {
        'accept': 'application/json',
        'x-api-key': LANGFLOW_API_KEY
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error getting workflow status:', error);
  }
};

getWorkflowStatus();
```

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

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

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

```python
import requests

url = f"{LANGFLOW_SERVER_URL}/api/v2/workflows/stop"
headers = {
    "Content-Type": "application/json",
    "x-api-key": LANGFLOW_API_KEY
}
payload = {
    "job_id": "job_id_1234567890"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())
```

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

```typescript
import axios from 'axios';

const url = `${LANGFLOW_SERVER_URL}/api/v2/workflows/stop`;

const payload = {
  job_id: "job_id_1234567890"
};

const stopWorkflow = async () => {
  try {
    const response = await axios.post(url, payload, {
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': LANGFLOW_API_KEY
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error('Error stopping workflow:', error);
  }
};

stopWorkflow();
```

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

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

</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."
}
```

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