Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
invoke
/
async
Invoke Agent (Async)
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/invoke/async \
  --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>"
}
'
{
  "id": "<string>",
  "agent_id": "<string>",
  "organization_id": "<string>",
  "input": {
    "text": "",
    "files": [],
    "user": {
      "email": "<string>",
      "display_name": "<string>",
      "id": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "additional_attributes": {},
      "role": "member",
      "is_super_admin": false,
      "timezone": "<string>"
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "status": "pending",
  "internal_status": "<string>",
  "last_executed_node_id": "<string>",
  "agent_version": "<string>",
  "started_at": "2023-11-07T05:31:56Z",
  "paused_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "result": "<string>",
  "parent_execution": "<string>",
  "sub_executions": [],
  "finished_sub_executions": [],
  "should_update_parent": false,
  "is_manually_stopped": false,
  "is_background": false,
  "payload_extension": {},
  "hitl_request": {
    "wait_node_id": "<string>"
  },
  "pending_eca_request": {
    "connector_name": "<string>",
    "auth_url": "<string>"
  },
  "source": "<string>",
  "worker_id": "<string>",
  "additional_context": "<string>",
  "instructions_override": "<string>",
  "expected_output": "<string>",
  "test_run_node_id": "<string>",
  "is_orchestration": false,
  "is_gateway": false,
  "output_format": "text",
  "voice_id": "<string>",
  "output_schema": {},
  "events_streaming": false,
  "used_mutating_tools": false,
  "is_continuous": false,
  "mcp_servers": [],
  "triggering_agent_id": "<string>",
  "title": "<string>",
  "think_mode": "default",
  "disable_attachment_injection": false,
  "deep_planning": {
    "enabled": false,
    "enforce": false,
    "started": false,
    "question_raised": false,
    "tasks": []
  },
  "execution_attempts": 1,
  "user_tokens": {},
  "user_oidc_token": "<string>",
  "return_metrics": false,
  "tokens": {
    "completion_tokens": 0,
    "prompt_tokens": 0,
    "total_tokens": 0
  },
  "llm_model_provider": "<string>",
  "llm_model_name": "<string>"
}
Invoke an agent asynchronously. Returns immediately with a task ID and status: "pending". Poll the Get Task endpoint to check when results are ready. Use this for long-running tasks, background processing, or when you don’t want to block a request.

​
Path Parameters

​
agent_id
string
required
Agent ID (UUID)

​
Request Body

The request body is identical to Invoke Agent (Sync).
  • input.text is required
  • input.user.id is required
  • input.user.email is required
  • user_oidc_token is optional for MCP OAuth-backed tools
​
input
object
required
​
user_oidc_token
string
Optional OIDC token for MCP OAuth-authenticated tools.
​
id
string
Thread ID for multi-turn conversations. Pass the id from a previous task to continue the conversation.
​
disable_attachment_injection
boolean
default:"false"
When true, files in input.files are not injected into the LLM context window. See Invoke Sync: Processing Files.
​
think_mode
string
default:"default"
default or harder. Controls reasoning depth.
​
instructions_override
string
Additional instructions appended to the system prompt for this invocation only.
​
additional_context
string
Extra context appended to the agent’s system prompt for this invocation only. Unlike instructions_override (which adds behavioral instructions), this supplies supplementary facts or context the agent should consider for this run — e.g. relevant background data, the current state of an external system, or a user’s recent activity.
​
expected_output
string
Natural-language description of desired output
​
llm_model_provider
string
Per-execution LLM provider override. See Invoke Sync: Per-Execution LLM Override.
​
llm_model_name
string
Per-execution model override. See Invoke Sync: Per-Execution LLM Override.
​
llm_reasoning_effort
string
default:"medium"
Per-execution reasoning-effort override (low | medium | high | xhigh). See Invoke Sync: Per-Execution LLM Override.

​
Query Parameters

​
version
string
Agent version to invoke. Defaults to latest deployed. Use "draft" to test undeployed changes.

​
Response

Returns immediately with the task object in pending state.
​
id
string
Task ID — use this to poll for results via Get Task
​
status
string
Always pending on initial return. Transitions to executing → completed (or failed/error).
​
result
string | null
null until the task completes

​
Basic Example

curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke/async" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Analyze competitor pricing for Q1 2026"}}'
Response (immediate): 
{
  "id": "81250b20-e9d7-4b3b-9995-07dc72b4bb59",
  "agent_id": "<agent-id>",
  "status": "pending",
  "result": null,
  "created_at": "2026-02-07T02:13:26.325626Z"
}

​
Polling for Results

# 1. Start the async task
TASK_ID=$(curl -s -X POST "https://api.xpander.ai/v1/agents/<agent-id>/invoke/async" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <your-api-key>" \
  -d '{"input": {"text": "Generate a market report"}}' | jq -r '.id')

echo "Task started: $TASK_ID"

# 2. Poll until done
while true; do
  RESPONSE=$(curl -s "https://api.xpander.ai/v1/tasks/$TASK_ID" \
    -H "x-api-key: <your-api-key>")

  STATUS=$(echo "$RESPONSE" | jq -r '.status')
  echo "Status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "error" ]; then
    echo "$RESPONSE" | jq -r '.result'
    break
  fi

  sleep 2
done

​
Example Response (After Completion)

Poll the task after it finishes to get the full result: 
{
  "id": "81250b20-e9d7-4b3b-9995-07dc72b4bb59",
  "agent_id": "<agent-id>",
  "status": "completed",
  "input": {
    "text": "Analyze competitor pricing for Q1 2026",
    "user": null
  },
  "result": "Based on my analysis, the three main competitors...",
  "created_at": "2026-02-07T02:13:26.325626Z",
  "finished_at": "2026-02-07T02:13:41.897000Z",
  "source": "api"
}

​
Task Status Flow

pending → executing → completed | failed | error | stopped
For multi-turn conversations, always wait for a task to reach completed before sending the next message with the same id. Sending a follow-up while the previous task is still executing may cause unexpected behavior.

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Query Parameters

​
version
string | null

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

Task creation response model.

Extends AgentExecution with additional agent_id field.

​
id
string
required
​
agent_id
string
required
​
organization_id
string
required
​
input
AgentExecutionInput · object
required
​
created_at
string<date-time>
required
​
status
enum<string> | null
default:pending
Available options:
pending,
executing,
paused,
error,
failed,
completed,
stopped
​
internal_status
string | null
​
last_executed_node_id
string | null
​
agent_version
string | null
​
started_at
string<date-time> | null
​
paused_at
string<date-time> | null
​
finished_at
string<date-time> | null
​
result
string | null
​
parent_execution
string | null
​
sub_executions
string[] | null
​
finished_sub_executions
string[] | null
​
should_update_parent
boolean | null
default:false
​
is_manually_stopped
boolean | null
default:false
​
is_background
boolean | null
default:false
​
payload_extension
Payload Extension · object
​
hitl_request
HumanInTheLoopRequest · object

Model representing human-in-the-loop approval records for tasks.

Attributes: wait_node_id (str): The id of the node that triggered this HITL.

​
pending_eca_request
PendingECARequest · object
​
source
string | null
​
worker_id
string | null
​
additional_context
string | null
​
instructions_override
string | null
​
expected_output
string | null
​
test_run_node_id
string | null
​
is_orchestration
boolean | null
default:false
​
is_gateway
boolean | null
default:false
​
output_format
enum<string> | null
default:text
Available options:
text,
markdown,
json,
voice
​
voice_id
string | null
​
output_schema
Output Schema · object
​
events_streaming
boolean | null
default:false
​
used_mutating_tools
boolean | null
default:false
​
is_continuous
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
​
deep_planning
DeepPlanning · object
​
execution_attempts
integer | null
default:1
​
user_tokens
User Tokens · object
​
user_oidc_token
string | null
​
return_metrics
boolean | null
default:false
​
tokens
LLMTokens · object
​
llm_model_provider
string | null

Snapshot of the LLM provider used for this execution (request override or agent default at run time).

​
llm_model_name
string | null

Snapshot of the LLM model name used for this execution (request override or agent default at run time).

​
llm_reasoning_effort
enum<string> | null

Snapshot of the reasoning effort applied during this execution, when supported by the model.

Available options:
low,
medium,
high,
xhigh