Skip to main content
POST
/
v1
/
workflows
/
{workflow_id}
/
invoke
/
stream
Invoke Workflow (Stream)
curl --request POST \
  --url https://api.xpander.ai/v1/workflows/{workflow_id}/invoke/stream \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "input": {
    "text": "",
    "files": [],
    "user": {
      "email": "<string>",
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "additional_attributes": {},
      "role": "member",
      "is_super_admin": false,
      "timezone": "<string>"
    }
  },
  "id": "<string>",
  "payload_extension": {},
  "parent_execution_id": "<string>",
  "worker_id": "<string>",
  "source": "<string>",
  "output_schema": {},
  "run_locally": false,
  "additional_context": "<string>",
  "instructions_override": "<string>",
  "test_run_node_id": "<string>",
  "expected_output": "<string>",
  "events_streaming": false,
  "mcp_servers": [],
  "triggering_agent_id": "<string>",
  "title": "<string>",
  "think_mode": "default",
  "disable_attachment_injection": false,
  "user_tokens": {},
  "user_oidc_token": "<string>",
  "return_metrics": false,
  "llm_model_provider": "<string>",
  "llm_model_name": "<string>"
}
'
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
Invoke a workflow with real-time streaming via Server-Sent Events (SSE). Receive live updates as the pipeline progresses through each node on the canvas — including tool calls, agent reasoning, sub-agent triggers, and the final result.

​
Path Parameters

​
workflow_id
string
required
Workflow ID (UUID)

​
Query Parameters

​
version
string
The workflow version to invoke. Defaults to the latest deployed version.

​
Request Body

Same as Invoke Workflow (Sync) — see that page for full request body documentation.

​
Response

Returns a text/event-stream response with Server-Sent Events. Each event contains a JSON payload with task update information. Events are sent as the workflow executes, including status changes, intermediate results, and the final TaskFinished event.

​
Example Request

curl -N -X POST "https://api.xpander.ai/v1/workflows/<workflow-id>/invoke/stream" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Generate a comprehensive report"}}'

​
Notes

  • The stream ends with a TaskFinished event type
  • Each SSE event is a data: line containing a JSON object
  • Use Cache-Control: no-cache and Connection: keep-alive headers for best results
  • Ideal for building real-time UIs that show pipeline progress across nodes

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
workflow_id
string
required

Query Parameters

​
version
string | null

The workflow version to invoke. default = latest

Body

application/json
​
input
AgentExecutionInput · object
required
​
id
string | null
​
payload_extension
Payload Extension · object
​
parent_execution_id
string | null
​
worker_id
string | null
​
source
string | null
​
output_format
enum<string> | null
Available options:
text,
markdown,
json,
voice
​
output_schema
Output Schema · object
​
run_locally
boolean | null
default:false
​
additional_context
string | null
​
instructions_override
string | null
​
test_run_node_id
string | null
​
expected_output
string | null
​
events_streaming
boolean | null
default:false
​
mcp_servers
Mcp Servers · object[] | null
​
triggering_agent_id
string | null
​
title
string | null
​
think_mode
enum<string> | null
default:default
Available options:
default,
harder
​
disable_attachment_injection
boolean | null
default:false
​
user_tokens
User Tokens · object
​
user_oidc_token
string | null
​
return_metrics
boolean | null
default:false
​
llm_model_provider
string | null

Per-execution override for the LLM provider (e.g. 'openai', 'anthropic'). Falls back to the agent's configured provider when unset.

​
llm_model_name
string | null

Per-execution override for the LLM model name. Falls back to the agent's configured model when unset.

​
llm_reasoning_effort
enum<string> | null

Per-execution override for reasoning effort on reasoning-capable models.

Available options:
low,
medium,
high,
xhigh
​
source_node_type
enum<string> | null

Surface that created this execution (mirrored to AgentExecutionHistory.source_node_type). Falls back to SourceNodeType.SDK at persist time when unset.

Available options:
workbench,
sdk,
task,
assistant,
webhook,
mcp,
a2a,
telegram,
slack

Response

Successful Response