Skip to main content
GET
/
v1
/
tasks
/
{task_id}
Get Task
curl --request GET \
  --url https://api.xpander.ai/v1/tasks/{task_id} \
  --header 'x-api-key: <api-key>'
{
  "id": "<string>",
  "agent_id": "<string>",
  "organization_id": "<string>",
  "input": {
    "text": "",
    "files": [],
    "user": {
      "id": "<string>",
      "email": "<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": [],
  "is_manually_stopped": 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,
  "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>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt

Use this file to discover all available pages before exploring further.

Get complete details about a task/thread record including its current status, latest input, latest result, and execution timing. This endpoint is essential for polling async tasks and for inspecting the latest turn of a continued conversation.

​
Path Parameters

​
task_id
string
required
Unique identifier of the task to retrieve (UUID format)

​
Response

​
id
string
Task/thread identifier. Reuse this as id in later invokes to continue the same conversation.
​
agent_id
string
UUID of the agent that executed this task
​
organization_id
string
UUID of the organization that owns this task
​
input
object
Latest input stored on this task/thread record
​
status
string
Current task status: pending, executing, paused, error, failed, completed, or stopped
​
result
string
Latest task result. This is usually plain text or markdown. Only parse it as JSON if you explicitly requested JSON/structured output.
​
output_format
string
Output format for the latest result, such as markdown or json
​
created_at
string
ISO 8601 timestamp of when the task was created
​
started_at
string
ISO 8601 timestamp of when execution began (null if not started)
​
finished_at
string
ISO 8601 timestamp of when the task finished (null if still running)
​
source
string
Source of the task creation: api, sdk, dashboard, webhook
​
events_streaming
boolean
Whether the task used event streaming
​
sub_executions
array
Array of sub-task UUIDs spawned by this task
​
parent_execution
string
UUID of parent task if this is a sub-task (null otherwise)
​
payload_extension
object
Additional metadata (nullable)
In a multi-turn conversation, this endpoint shows the latest input and latest result for the reused task/thread ID. Use Get Task Thread or Get Task Thread (Full) for the full message history.

​
Example Request

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>"

​
Example Response

{
  "id": "fbd08e4d-cfa7-4838-b6e6-e51855ac2ba3",
  "agent_id": "<agent-id>",
  "organization_id": "<org-id>",
  "input": {
    "text": "Reply with exactly SECOND",
    "files": [],
    "user": null
  },
  "status": "completed",
  "created_at": "2026-03-23T00:45:26.965823Z",
  "started_at": null,
  "finished_at": "2026-03-23T00:45:30.532954Z",
  "result": "SECOND",
  "source": "api",
  "output_format": "markdown",
  "events_streaming": true,
  "sub_executions": [],
  "parent_execution": null,
  "payload_extension": null
}

​
Extracting Results

For normal text or markdown responses: 
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>" | jq -r '.result'
Only use fromjson when you explicitly requested JSON output: 
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks/<task-id>" | jq '.result | fromjson'

​
Status Polling Pattern

For async workflows, poll until status is no longer pending or executing: 
# Poll every 2 seconds until task completes
while true; do
  TASK=$(curl -s -H "x-api-key: <your-api-key>" \
    "https://api.xpander.ai/v1/tasks/<task-id>")

  STATUS=$(echo $TASK | jq -r '.status')

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

  sleep 2
done

​
Use Cases

  • Retrieve task results - Get final output after async execution
  • Check execution status - Monitor if task is still executing
  • Track timing - See created_at, started_at, finished_at for performance analysis
  • Get latest-turn details - Review the most recent input and output for a continued conversation

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
task_id
string
required

Response

Successful Response

​
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
​
is_manually_stopped
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
​
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 effective LLM provider used for this execution. Reflects the per-execution override when supplied on the invocation request, otherwise falls back to the agent's configured provider.

​
llm_model_name
string | null

Snapshot of the effective model name used for this execution. Reflects the per-execution override when supplied on the invocation request, otherwise falls back to the agent's configured model.

​
llm_reasoning_effort
enum<string> | null

Snapshot of the effective reasoning effort used for this execution. Reflects the per-execution override when supplied on the invocation request, otherwise falls back to the agent's configured reasoning effort.

Available options:
low,
medium,
high,
xhigh