Skip to main content
Version: 1.10.x

OpenAI Responses API

Langflow includes an endpoint that is compatible with the OpenAI Responses API. It is available at POST /api/v1/responses.

This endpoint allows you to use existing OpenAI client libraries with minimal code changes. You only need to replace the model name, such as gpt-4, with your flow_id. You can find Flow IDs in the code snippets on the API access pane or in a flow's URL.

Prerequisites​

To be compatible with Langflow's OpenAI Responses API endpoint, your flow and request must adhere to the following requirements:

  • Chat Input: Your flow must contain a Chat Input component. Flows without this component return an error when passed to this endpoint. The component types ChatInput and Chat Input are recognized as chat inputs.
  • Tools: The tools parameter isn't supported, and returns an error if provided.
  • Model Names: In your request, the model field must contain a valid flow ID or endpoint name.
  • Authentication: All requests require an API key passed in the x-api-key header. For more information, see API keys and authentication.

Additional configuration for OpenAI client libraries​

This endpoint is compatible with OpenAI's API, but requires special configuration when using OpenAI client libraries. Langflow uses x-api-key headers for authentication, while OpenAI uses Authorization: Bearer headers. When sending requests to Langflow with OpenAI client libraries, you must configure custom headers and include an api_key configuration. The api_key parameter can have any value, such as "dummy-api-key" in the client examples, as the actual authentication is handled through the default_headers configuration.

In the following examples, replace the values for LANGFLOW_SERVER_URL, LANGFLOW_API_KEY, and FLOW_ID with values from your deployment.

import os

from openai import OpenAI

base = (os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")).rstrip("/")
api_key = os.environ.get("LANGFLOW_API_KEY", "")
flow_id = os.environ.get("FLOW_ID", "")

client = OpenAI(
    base_url=f"{base}/api/v1/",
    default_headers={"x-api-key": api_key},
    api_key="dummy-api-key",  # Required by OpenAI SDK but not used by Langflow
)

try:
    response = client.responses.create(
        model=flow_id,
        input="There is an event that happens on the second wednesday of every month. What are the event dates in 2026?",
    )
except Exception as exc:
    # Empty bootstrap flows return an error body; use a flow with ChatInput + ChatOutput in the UI.
    print(exc)
else:
    try:
        print(response.output_text)
    except Exception:
        print(response)
Response
Here are the event dates for the second Wednesday of each month in 2026:
- January 14, 2026
- February 11, 2026
- March 11, 2026
- April 8, 2026
- May 13, 2026
- June 10, 2026
- July 8, 2026
- August 12, 2026
- September 9, 2026
- October 14, 2026
- November 11, 2026
- December 9, 2026
If you need these in a different format or want a downloadable calendar, let me know!

Example request​

import os

import requests

url = f"{os.getenv('LANGFLOW_SERVER_URL', '')}/api/v1/responses"

headers = {
    "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}",
    "Content-Type": "application/json",
}

payload = {"model": "$YOUR_FLOW_ID", "input": "Hello, how are you?", "stream": False}

response = requests.request("POST", url, headers=headers, json=payload)
response.raise_for_status()

print(response.text)

Headers​

HeaderRequiredDescriptionExample
x-api-keyYesYour Langflow API key for authentication"sk-..."
Content-TypeYesSpecifies the JSON format"application/json"
X-LANGFLOW-GLOBAL-VAR-*NoGlobal variables for the flow"X-LANGFLOW-GLOBAL-VAR-API_​KEY: sk-..." For more, see Pass global variables to your flows in headers.

Request body​

FieldTypeRequiredDefaultDescription
modelstringYes-The flow ID or endpoint name to execute.
inputstringYes-The input text to process.
streambooleanNofalseWhether to stream the response.
backgroundbooleanNofalseWhether to process in background.
toolslist[Any]NonullTools are not supported yet.
previous_​response_​idstringNonullID of previous response to continue conversation. For more, see Continue conversations with response and session IDs.
includelist[string]NonullAdditional response data to include, such as ['tool_​call.results']. For more, see Retrieve tool call results.

Example response​

{
  "id": "e5e8ef8a-7efd-4090-a110-6aca082bceb7",
  "object": "response",
  "created_at": 1756837941,
  "status": "completed",
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "output": [
    {
      "type": "message",
      "id": "msg_e5e8ef8a-7efd-4090-a110-6aca082bceb7",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! I'm here and ready to help. How can I assist you today?",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {"effort": null, "summary": null},
  "store": true,
  "temperature": 1.0,
  "text": {"format": {"type": "text"}},
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": null,
  "user": null,
  "metadata": {}
}

Response body​

The response contains fields that Langflow sets dynamically and fields that use OpenAI-compatible defaults.

The OpenAI-compatible default values shown above are currently fixed and cannot be modified via the request. They are included to maintain API compatibility and provide a consistent response format.

For your requests, you will only be setting the dynamic fields. The default values are documented here for completeness and to show the full response structure.

Fields set dynamically by Langflow:

FieldTypeDescription
idstringUnique response identifier.
created_​atintUnix timestamp of response creation.
modelstringThe flow ID that was executed.
outputlist[dict]Array of output items (messages, tool calls, etc.).
previous_​response_​idstringID of previous response if continuing conversation.
usagedictToken usage statistics if the usage field is available. Contains prompt_​tokens, completion_​tokens, and total_​tokens.
Fields with OpenAI-compatible default values
FieldTypeDefault ValueDescription
objectstring"response"Always "response".
statusstring"completed"Response status: "completed", "in_​progress", or "failed".
errordictnullError details (if any).
incomplete_​detailsdictnullIncomplete response details (if any).
instructionsstringnullResponse instructions (if any).
max_​output_​tokensintnullMaximum output tokens (if any).
parallel_​tool_​callsbooleantrueWhether parallel tool calls are enabled.
reasoningdict{"effort": null, "summary": null}Reasoning information with effort and summary.
storebooleantrueWhether response is stored.
temperaturefloat1.0Temperature setting.
textdict{"format": {"type": "text"}}Text format configuration.
tool_​choicestring"auto"Tool choice setting.
toolslist[dict][]Available tools.
top_​pfloat1.0Top-p setting.
truncationstring"disabled"Truncation setting.
usagedictnullToken usage statistics. Set dynamically when available from flow components, otherwise null. See Token usage tracking.
userstringnullUser identifier (if any).
metadatadict{}Additional metadata.

Example streaming request​

When you set "stream": true with your request, the API returns a stream where each chunk contains a small piece of the response as it's generated. This provides a real-time experience where users can see the AI's output appear word by word, similar to ChatGPT's typing effect.

import os

import requests

url = f"{os.getenv('LANGFLOW_SERVER_URL', '')}/api/v1/responses"

headers = {
    "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}",
    "Content-Type": "application/json",
}

payload = {"model": "$FLOW_ID", "input": "Tell me a story about a robot", "stream": True}

response = requests.request("POST", url, headers=headers, json=payload)
response.raise_for_status()

print(response.text)
Result
{
  "id": "f7fcea36-f128-41c4-9ac1-e683137375d5",
  "object": "response.chunk",
  "created": 1756838094,
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "delta": {
    "content": "Once"
  },
  "status": null
}

Streaming response body​

FieldTypeDescription
idstringUnique response identifier.
objectstringAlways "response.chunk".
createdintUnix timestamp of chunk creation.
modelstringThe flow ID that was executed.
deltadictThe new content chunk.
statusstringResponse status: "completed", "in_​progress", or "failed" (optional).

The stream continues until a final chunk with "status": "completed" indicates the response is finished.

Final completion chunk
{
  "id": "f7fcea36-f128-41c4-9ac1-e683137375d5",
  "object": "response.chunk",
  "created": 1756838094,
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "delta": {},
  "status": "completed"
}

Continue conversations with response and session IDs​

Conversation continuity allows you to maintain context across multiple API calls, enabling multi-turn conversations with your flows. This is essential for building chat applications where users can have ongoing conversations.

When you make a request, the API returns a response with an id field. You can use this id as the previous_response_id in your next request to continue the conversation from where it left off.

First Message:

import os

import requests

base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
flow_id = os.environ.get("FLOW_ID", "")
api_key = os.environ.get("LANGFLOW_API_KEY", "")

url = f"{base}/api/v1/responses"

headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
}

payload = {
    "model": flow_id,
    "input": "Hello, my name is Alice",
    "stream": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()

print(response.text)
Result
{
  "id": "c45f4ac8-772b-4675-8551-c560b1afd590",
  "object": "response",
  "created_at": 1756839042,
  "status": "completed",
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "output": [
    {
      "type": "message",
      "id": "msg_c45f4ac8-772b-4675-8551-c560b1afd590",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Hello, Alice! How can I assist you today?",
          "annotations": []
        }
      ]
    }
  ],
  "previous_response_id": null
}

Follow-up message:

# Continuation requests use the same endpoint; add `previous_response_id` from a prior
# response's `id` field. The bootstrap flow is empty; use a Playground flow with ChatInput +
# ChatOutput for a full run. Same first message as continue-conversations-with-response-and-session-ids.py.

import os

import requests

base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
flow_id = os.environ.get("FLOW_ID", "")
api_key = os.environ.get("LANGFLOW_API_KEY", "")

url = f"{base}/api/v1/responses"

headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
}

payload = {
    "model": flow_id,
    "input": "Hello, my name is Alice",
    "stream": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()

print(response.text)
Result
{
  "id": "c45f4ac8-772b-4675-8551-c560b1afd590",
  "object": "response",
  "created_at": 1756839043,
  "status": "completed",
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "output": [
    {
      "type": "message",
      "id": "msg_c45f4ac8-772b-4675-8551-c560b1afd590",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Your name is Alice. How can I help you today?",
          "annotations": []
        }
      ]
    }
  ],
  "previous_response_id": "c45f4ac8-772b-4675-8551-c560b1afd590"
}

Optionally, you can use your own session ID values for the previous_response_id:

# Same pattern as continue-conversations-with-response-and-session-ids-2.py; you can pass
# `previous_response_id` from the prior turn (or a session id your app stores).

import os

import requests

base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
flow_id = os.environ.get("FLOW_ID", "")
api_key = os.environ.get("LANGFLOW_API_KEY", "")

url = f"{base}/api/v1/responses"

headers = {
    "x-api-key": api_key,
    "Content-Type": "application/json",
}

payload = {
    "model": flow_id,
    "input": "Hello, my name is Alice",
    "stream": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()

print(response.text)
Result

This example uses the same flow as the other previous_response_id examples, but the LLM had not yet been introduced to Alice in the specified session:

{
  "id": "session-alice-1756839048",
  "object": "response",
  "created_at": 1756839048,
  "status": "completed",
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "output": [
    {
      "type": "message",
      "id": "msg_session-alice-1756839048",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "I don't have access to your name unless you tell me. If you'd like, you can share your name, and I'll remember it for this conversation!",
          "annotations": []
        }
      ]
    }
  ],
  "previous_response_id": "session-alice-1756839048"
}

Retrieve tool call results​

When you send a request to the /api/v1/responses endpoint to run a flow that includes tools or function calls, you can retrieve the raw tool execution details by adding "include": ["tool_call.results"] to the request payload.

Without the include parameter, tool calls return basic function call information, but not the raw tool results. For example:

{
  "id": "fc_1",
  "type": "function_call",
  "status": "completed",
  "name": "evaluate_expression",
  "arguments": "{\"expression\": \"15*23\"}"
},

To get the raw results of each tool execution, add include: ["tool_call.results"] to the request payload:

import os

import requests

base = os.environ.get("LANGFLOW_URL") or os.environ.get("LANGFLOW_SERVER_URL", "")
flow_id = os.environ.get("FLOW_ID", "")
api_key = os.environ.get("LANGFLOW_API_KEY", "")

url = f"{base}/api/v1/responses"

headers = {
    "Content-Type": "application/json",
    "x-api-key": api_key,
}

payload = {
    "model": flow_id,
    "input": "Calculate 23 * 15 and show me the result",
    "stream": False,
    "include": ["tool_call.results"],
}

response = requests.post(url, headers=headers, json=payload, timeout=120)
response.raise_for_status()

print(response.text)

The response now includes the tool call's results. For example:

{
  "id": "evaluate_expression_1",
  "type": "tool_call",
  "tool_name": "evaluate_expression",
  "queries": ["15*23"],
  "results": {"result": "345"}
}
Result
{
  "id": "a6e5511e-71f8-457a-88d2-7d8c6ea34e36",
  "object": "response",
  "created_at": 1756835379,
  "status": "completed",
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "model": "ced2ec91-f325-4bf0-8754-f3198c2b1563",
  "output": [
    {
      "id": "evaluate_expression_1",
      "queries": [
        "15*23"
      ],
      "status": "completed",
      "tool_name": "evaluate_expression",
      "type": "tool_call",
      "results": {
        "result": "345"
      }
    },
    {
      "type": "message",
      "id": "msg_a6e5511e-71f8-457a-88d2-7d8c6ea34e36",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "The result of 23 * 15 is 345.",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "summary": null
  },
  "store": true,
  "temperature": 1.0,
  "text": {
    "format": {
      "type": "text"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "truncation": "disabled",
  "usage": null,
  "user": null,
  "metadata": {}
}

Variables passed with X-LANGFLOW-GLOBAL-VAR-{VARIABLE_NAME} are always available to your flow, regardless of whether they exist in the database.

If your flow components reference variables that aren't provided in headers or your Langflow database, the flow fails by default.

To avoid this, you can set the FALLBACK_TO_ENV_VARS environment variable is true, which allows the flow to use values from the .env file if they aren't otherwise specified.

In the above example, OPENAI_API_KEY will fall back to the database variable if not provided in the header. USER_ID and ENVIRONMENT will fall back to environment variables if FALLBACK_TO_ENV_VARS is enabled. Otherwise, the flow fails.

Token usage tracking​

The OpenAI Responses API endpoint tracks token usage when your flow uses language model components that provide token usage information. The usage field in the response contains statistics about the number of tokens used for the request and response.

Token usage is automatically extracted from the flow execution results when the usage field is available. The usage field follows OpenAI's format with prompt_tokens, completion_tokens, and total_tokens fields. If token usage information is not available from the flow components, the usage field is null.

The usage field is always present in the response, either with token counts or as null. The conditional checks shown in the examples below are optional defensive programming to handle cases where usage might not be available.

import os

import requests

url = f"{os.getenv('LANGFLOW_SERVER_URL', '')}/api/v1/responses"

headers = {
    "x-api-key": f"{os.getenv('LANGFLOW_API_KEY', '')}",
    "Content-Type": "application/json",
}

payload = {"model": "FLOW_ID", "input": "Explain quantum computing in simple terms", "stream": False}

response = requests.request("POST", url, headers=headers, json=payload)
response.raise_for_status()

print(response.text)

Was this page helpful?

Support
Search