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": "Explain the benefits of your product in detail"
  }
}
'
{
  "id": "04dbe342-27ef-4fcb-bc16-f19457e892b3",
  "agent_id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
  "status": "pending",
  "created_at": "2026-02-07T06:18:47.438043Z",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031"
}
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). Only input.text is required.
​
input
object
required
​
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.
​
expected_output
string
Natural-language description of desired output

​
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

Body

application/json
​
input
AgentExecutionInput · object
required

The input to send to the agent

​
id
string | null

Thread ID for multi-turn conversations. Pass the id from a previous task to continue the conversation.

​
expected_output
string | null

Natural-language description of the desired output

​
think_mode
enum<string> | null

Controls the agent's reasoning depth. "default" for standard reasoning, "harder" for deeper analysis.

Available options:
default,
harder
​
disable_attachment_injection
boolean | null

When true, files in input.files are not injected into the LLM context window

​
instructions_override
string | null

Additional instructions appended to the agent's system prompt for this invocation only. Use this to adjust behavior per-request without changing the agent's configuration.

Response

Successful Response

Response from invoking an agent. Contains the execution details and result.

​
id
string
required

Unique identifier for this execution

​
agent_id
string
required

ID of the agent that was invoked

​
organization_id
string
required

Organization UUID

​
input
AgentExecutionInput · object
required

The input that was sent to the agent

​
status
enum<string> | null
required

Current status of the execution (pending, executing, completed, etc.)

Available options:
pending,
executing,
paused,
error,
failed,
completed,
stopped
​
created_at
string<date-time>
required

ISO 8601 timestamp when the task was created

​
result
string | null

The agent's response. If output_format is json, this is a JSON string - parse it with JSON.parse() or jq

​
started_at
string<date-time> | null

ISO 8601 timestamp when the task started executing

​
finished_at
string<date-time> | null

ISO 8601 timestamp when the task completed