> ## 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 Task
> Retrieve detailed information about a specific task by its unique identifier
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
Unique identifier of the task to retrieve (UUID format)
## Response
Task/thread identifier. Reuse this as `id` in later invokes to continue the same conversation.
UUID of the agent that executed this task
UUID of the organization that owns this task
Latest input stored on this task/thread record
Text message or query
Array of file references (if any)
User information (nullable)
Current task status: `pending`, `executing`, `paused`, `error`, `failed`, `completed`, or `stopped`
Latest task result. This is usually plain text or markdown. Only parse it as JSON if you explicitly requested JSON/structured output.
Output format for the latest result, such as `markdown` or `json`
ISO 8601 timestamp of when the task was created
ISO 8601 timestamp of when execution began (null if not started)
ISO 8601 timestamp of when the task finished (null if still running)
Source of the task creation: `api`, `sdk`, `dashboard`, `webhook`
Whether the task used event streaming
Array of sub-task UUIDs spawned by this task
UUID of parent task if this is a sub-task (null otherwise)
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](/api-reference/v1/tasks/get-thread) or [Get Task Thread (Full)](/api-reference/v1/tasks/get-thread-full) for the full message history.
## Example Request
```bash theme={"dark"}
curl -X GET -H "x-api-key: " \
"https://api.xpander.ai/v1/tasks/"
```
## Example Response
```json theme={"dark"}
{
"id": "fbd08e4d-cfa7-4838-b6e6-e51855ac2ba3",
"agent_id": "",
"organization_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:
```bash theme={"dark"}
curl -X GET -H "x-api-key: " \
"https://api.xpander.ai/v1/tasks/" | jq -r '.result'
```
Only use `fromjson` when you explicitly requested JSON output:
```bash theme={"dark"}
curl -X GET -H "x-api-key: " \
"https://api.xpander.ai/v1/tasks/" | jq '.result | fromjson'
```
## Status Polling Pattern
For async workflows, poll until `status` is no longer `pending` or `executing`:
```bash theme={"dark"}
# Poll every 2 seconds until task completes
while true; do
TASK=$(curl -s -H "x-api-key: " \
"https://api.xpander.ai/v1/tasks/")
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
## OpenAPI
````yaml GET /v1/tasks/{task_id}
openapi: 3.1.0
info:
title: xpander.ai API Service
description: |2-
The xpander.ai API Service provides a unified REST API for managing AI agents,
executing tasks, managing knowledge bases, and integrating with external systems.
Features:
- Agent Management: Create, update, deploy, and delete AI agents
- Task Execution: Invoke agents with support for sync, async, and streaming modes
- Knowledge Bases: Manage knowledge bases and documents for RAG workflows
- Tools: Discover, connect, and attach tools (connectors, custom functions, MCP servers, sub-agents, workflows) to agents and workflows
- MCP Integration: Model Context Protocol support for standardized AI interactions
Authentication: All endpoints require authentication via either an API key (`x-api-key`) or an OAuth2 JWT (`Authorization: Bearer `).
version: '0.001'
servers:
- url: https://api.xpander.ai
security: []
paths:
/v1/tasks/{task_id}:
get:
tags:
- API v1
- Tasks
- Tasks CRUD
summary: Get Task
description: Get Task by ID
operationId: Get_Task_v1_tasks__task_id__get
parameters:
- name: task_id
in: path
required: true
schema:
type: string
title: Task Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AgentExecution'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- APIKeyHeader: []
components:
schemas:
AgentExecution:
properties:
id:
type: string
title: Id
agent_id:
type: string
title: Agent Id
organization_id:
type: string
title: Organization Id
input:
$ref: '#/components/schemas/AgentExecutionInput-Output'
status:
anyOf:
- $ref: >-
#/components/schemas/xpander_dev_utils__models__executions__AgentExecutionStatus
- type: 'null'
default: pending
internal_status:
anyOf:
- type: string
- type: 'null'
title: Internal Status
last_executed_node_id:
anyOf:
- type: string
- type: 'null'
title: Last Executed Node Id
agent_version:
anyOf:
- type: string
- type: 'null'
title: Agent Version
created_at:
type: string
format: date-time
title: Created At
started_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Started At
paused_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Paused At
finished_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Finished At
result:
anyOf:
- type: string
- type: 'null'
title: Result
parent_execution:
anyOf:
- type: string
- type: 'null'
title: Parent Execution
sub_executions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Sub Executions
default: []
finished_sub_executions:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Finished Sub Executions
default: []
should_update_parent:
anyOf:
- type: boolean
- type: 'null'
title: Should Update Parent
default: false
is_manually_stopped:
anyOf:
- type: boolean
- type: 'null'
title: Is Manually Stopped
default: false
is_background:
anyOf:
- type: boolean
- type: 'null'
title: Is Background
default: false
payload_extension:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Payload Extension
hitl_request:
anyOf:
- $ref: '#/components/schemas/HumanInTheLoopRequest'
- type: 'null'
pending_eca_request:
anyOf:
- $ref: '#/components/schemas/PendingECARequest'
- type: 'null'
source:
anyOf:
- type: string
- type: 'null'
title: Source
worker_id:
anyOf:
- type: string
- type: 'null'
title: Worker Id
additional_context:
anyOf:
- type: string
- type: 'null'
title: Additional Context
instructions_override:
anyOf:
- type: string
- type: 'null'
title: Instructions Override
expected_output:
anyOf:
- type: string
- type: 'null'
title: Expected Output
test_run_node_id:
anyOf:
- type: string
- type: 'null'
title: Test Run Node Id
is_orchestration:
anyOf:
- type: boolean
- type: 'null'
title: Is Orchestration
default: false
is_gateway:
anyOf:
- type: boolean
- type: 'null'
title: Is Gateway
default: false
output_format:
anyOf:
- $ref: '#/components/schemas/OutputFormat'
- type: 'null'
default: text
voice_id:
anyOf:
- type: string
- type: 'null'
title: Voice Id
output_schema:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Output Schema
events_streaming:
anyOf:
- type: boolean
- type: 'null'
title: Events Streaming
default: false
used_mutating_tools:
anyOf:
- type: boolean
- type: 'null'
title: Used Mutating Tools
default: false
is_continuous:
anyOf:
- type: boolean
- type: 'null'
title: Is Continuous
default: false
mcp_servers:
anyOf:
- items:
additionalProperties: true
type: object
type: array
- type: 'null'
title: Mcp Servers
default: []
triggering_agent_id:
anyOf:
- type: string
- type: 'null'
title: Triggering Agent Id
title:
anyOf:
- type: string
- type: 'null'
title: Title
think_mode:
anyOf:
- $ref: '#/components/schemas/ThinkMode'
- type: 'null'
default: default
disable_attachment_injection:
anyOf:
- type: boolean
- type: 'null'
title: Disable Attachment Injection
default: false
deep_planning:
anyOf:
- $ref: '#/components/schemas/DeepPlanning'
- type: 'null'
execution_attempts:
anyOf:
- type: integer
- type: 'null'
title: Execution Attempts
default: 1
user_tokens:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: User Tokens
user_oidc_token:
anyOf:
- type: string
- type: 'null'
title: User Oidc Token
return_metrics:
anyOf:
- type: boolean
- type: 'null'
title: Return Metrics
default: false
tokens:
anyOf:
- $ref: '#/components/schemas/LLMTokens'
- type: 'null'
llm_model_provider:
anyOf:
- type: string
- type: 'null'
title: Llm Model Provider
description: >-
Snapshot of the LLM provider used for this execution (request
override or agent default at run time).
llm_model_name:
anyOf:
- type: string
- type: 'null'
title: Llm Model Name
description: >-
Snapshot of the LLM model name used for this execution (request
override or agent default at run time).
llm_reasoning_effort:
anyOf:
- $ref: '#/components/schemas/LLMReasoningEffort'
- type: 'null'
description: >-
Snapshot of the reasoning effort applied during this execution, when
supported by the model.
type: object
required:
- id
- agent_id
- organization_id
- input
- created_at
title: AgentExecution
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
AgentExecutionInput-Output:
properties:
text:
anyOf:
- type: string
- type: 'null'
title: Text
default: ''
files:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Files
default: []
user:
anyOf:
- $ref: '#/components/schemas/User-Output'
- type: 'null'
type: object
title: AgentExecutionInput
xpander_dev_utils__models__executions__AgentExecutionStatus:
type: string
enum:
- pending
- executing
- paused
- error
- failed
- completed
- stopped
title: AgentExecutionStatus
HumanInTheLoopRequest:
properties:
wait_node_id:
type: string
title: Wait Node Id
type: object
required:
- wait_node_id
title: HumanInTheLoopRequest
description: |-
Model representing human-in-the-loop approval records for tasks.
Attributes:
wait_node_id (str): The id of the node that triggered this HITL.
PendingECARequest:
properties:
connector_name:
type: string
title: Connector Name
auth_url:
type: string
title: Auth Url
type: object
required:
- connector_name
- auth_url
title: PendingECARequest
OutputFormat:
type: string
enum:
- text
- markdown
- json
- voice
title: OutputFormat
ThinkMode:
type: string
enum:
- default
- harder
title: ThinkMode
DeepPlanning:
properties:
enabled:
anyOf:
- type: boolean
- type: 'null'
title: Enabled
default: false
enforce:
anyOf:
- type: boolean
- type: 'null'
title: Enforce
default: false
started:
anyOf:
- type: boolean
- type: 'null'
title: Started
default: false
question_raised:
anyOf:
- type: boolean
- type: 'null'
title: Question Raised
default: false
tasks:
anyOf:
- items:
$ref: '#/components/schemas/DeepPlanningItem'
type: array
- type: 'null'
title: Tasks
default: []
type: object
title: DeepPlanning
LLMTokens:
properties:
completion_tokens:
anyOf:
- type: integer
- type: 'null'
title: Completion Tokens
default: 0
prompt_tokens:
anyOf:
- type: integer
- type: 'null'
title: Prompt Tokens
default: 0
total_tokens:
anyOf:
- type: integer
- type: 'null'
title: Total Tokens
default: 0
type: object
title: LLMTokens
LLMReasoningEffort:
type: string
enum:
- low
- medium
- high
- xhigh
title: LLMReasoningEffort
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
User-Output:
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
first_name:
anyOf:
- type: string
- type: 'null'
title: First Name
last_name:
anyOf:
- type: string
- type: 'null'
title: Last Name
email:
type: string
title: Email
additional_attributes:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Additional Attributes
role:
anyOf:
- type: string
- type: 'null'
title: Role
default: member
is_super_admin:
anyOf:
- type: boolean
- type: 'null'
title: Is Super Admin
default: false
timezone:
anyOf:
- type: string
- type: 'null'
title: Timezone
display_name:
type: string
title: Display Name
readOnly: true
type: object
required:
- email
- display_name
title: User
description: |-
Represents the details of a user.
Attributes:
id (Optional[str]): The unique identifier of the user. Defaults to None.
first_name (Optional[str]): The first name of the user. Defaults to None.
last_name (Optional[str]): The last name of the user. Defaults to None.
email (str): The email address of the user. This field is required.
additional_attributes (Optional[dict]): Possible additional parameters for the assistant's service.
role (Optional[str]): The user's role in the organization. Defaults to "member".
is_super_admin (Optional[bool]): Whether the user is a super admin. Defaults to False.
timezone (Optional[str]): The user's timezone in IANA format (e.g. "America/New_York"). Defaults to None.
DeepPlanningItem:
properties:
id:
type: string
title: Id
title:
type: string
title: Title
description:
anyOf:
- type: string
- type: 'null'
title: Description
input:
anyOf:
- {}
- type: 'null'
title: Input
output:
anyOf:
- {}
- type: 'null'
title: Output
tool_name:
anyOf:
- type: string
- type: 'null'
title: Tool Name
completed:
anyOf:
- type: boolean
- type: 'null'
title: Completed
default: false
type: object
required:
- id
- title
title: DeepPlanningItem
securitySchemes:
APIKeyHeader:
type: apiKey
description: API Key for authentication
in: header
name: x-api-key
````