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": "04dbe342-27ef-4fcb-bc16-f19457e892b3",
  "agent_id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
  "status": "completed",
  "input": {
    "text": "How do I reset my password?",
    "files": []
  },
  "result": "To reset your password, visit the login page and click 'Forgot Password'. You'll receive a reset link via email within a few minutes.",
  "created_at": "2026-02-07T06:18:47.438043Z",
  "started_at": "2026-02-07T06:18:48.201887Z",
  "finished_at": "2026-02-07T06:18:55.784755Z",
  "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031"
}
Get complete details about a task including its current status, input, results, and execution timing. This endpoint is essential for polling async tasks and retrieving final results.

​
Path Parameters

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

​
Response

​
id
string
Unique identifier for the task (UUID)
​
agent_id
string
UUID of the agent that executed this task
​
organization_id
string
UUID of the organization that owns this task
​
input
object
Original input sent to the agent
​
status
string
Current task status: queued, running, completed, failed, cancelled
​
result
string
Task execution result as JSON string (present when status is completed)
​
output_format
string
Expected output format: text, json, or structured
​
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)

​
Example Request

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

​
Example Response

{
  "id": "e6cf93db-30c7-471b-a1a9-5051a2c9e4ba",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "input": {
    "text": "What is xpander.ai?",
    "files": [],
    "user": null
  },
  "status": "completed",
  "created_at": "2026-02-07T02:12:58.060662Z",
  "started_at": null,
  "finished_at": "2026-02-07T02:13:13.281503Z",
  "result": "{\"description\":\"Full-stack agent platform for AI workflow automation\"}",
  "source": "api",
  "output_format": "text",
  "events_streaming": true,
  "sub_executions": [],
  "parent_execution": null,
  "payload_extension": null
}

​
Extracting Results

To parse the JSON result field, use jq: 
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 queued or running: 
# 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 '.result | fromjson'
    break
  fi

  sleep 2
done

​
Use Cases

  • Retrieve task results - Get final output after async execution
  • Check execution status - Monitor if task is still running
  • Track timing - See created_at, started_at, finished_at for performance analysis
  • Get input details - Review what was sent to the agent

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
task_id
string
required

Response

Successful Response

​
id
string

Task/thread ID. Pass this back as id in your next request to continue the conversation.

​
agent_id
string

Unique identifier of the agent that executed this task

​
input
AgentExecutionInput · object

The input that was provided to the agent

​
status
enum<string> | null

Task execution status: pending, executing, paused, completed, failed, error, or stopped

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

ISO 8601 timestamp when the task was created

​
started_at
string<date-time> | null

ISO 8601 timestamp when the task started executing

​
paused_at
string<date-time> | null

ISO 8601 timestamp when the task was paused (for HITL scenarios)

​
finished_at
string<date-time> | null

ISO 8601 timestamp when the task completed

​
result
string | null

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

​
organization_id
string

Organization UUID