Skip to main content
GET
/
v1
/
agents
/
{agent_id}
/
tasks
Get Agent Tasks
curl --request GET \
  --url https://api.xpander.ai/v1/agents/{agent_id}/tasks \
  --header 'x-api-key: <api-key>'
{
  "items": [
    {
      "id": "<string>",
      "agent_id": "<string>",
      "organization_id": "<string>",
      "status": "pending",
      "user_id": "<string>",
      "parent_task_id": "<string>",
      "triggering_agent_id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z",
      "source_node_type": "<string>",
      "result": "<string>",
      "title": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "per_page": 123,
  "total_pages": 123
}
Get paginated task records for a specific agent with support for filtering by user, status, and parent task relationships. In multi-turn conversations, reusing an invocation id updates the same task/thread record instead of creating a brand-new top-level item for every turn.

​
Path Parameters

​
agent_id
string
required
Unique identifier of the agent (UUID format)

​
Query Parameters

​
page
integer
default:1
Page number (starting from 1)
​
per_page
integer
default:20
Items per page (maximum 50)
​
user_id
string
Filter by user ID who created the task
​
parent_task_id
string
Filter by parent task ID (for sub-tasks)
​
triggering_agent_id
string
Filter by triggering agent ID (parent calling agent in multi-agent workflows)
​
status
string
Filter by task execution status: pending, executing, paused, error, failed, completed, stopped
​
internal_status
string
Filter by internal task processing status

​
Response

​
items
array
Array of task objects
​
total
integer
Total number of tasks for this agent
​
page
integer
Current page number
​
per_page
integer
Number of items per page
​
total_pages
integer
Total number of pages available

​
Example Requests

​
List all tasks for an agent

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/<agent-id>/tasks?page=1&per_page=2"

​
Filter by status

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/<agent-id>/tasks?status=completed&page=1&per_page=10"

​
Filter by user

curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/agents/<agent-id>/tasks?user_id=<user-id>&page=1&per_page=10"

​
Example Response

{
  "items": [
    {
      "id": "fbd08e4d-cfa7-4838-b6e6-e51855ac2ba3",
      "agent_id": "<agent-id>",
      "user_id": null,
      "parent_task_id": null,
      "triggering_agent_id": null,
      "organization_id": "<org-id>",
      "status": "completed",
      "source_node_type": "sdk",
      "created_at": "2026-03-23T00:45:24.296117Z",
      "updated_at": "2026-03-23T00:45:31.040146Z",
      "title": "Reply with exactly SECOND",
      "result": "SECOND"
    }
  ],
  "total": 6,
  "page": 1,
  "per_page": 5,
  "total_pages": 2
}

​
Use Cases

  • Monitor Agent Activity: Track all tasks executed by a specific agent
  • Debug Workflows: Filter by parent_task_id to see sub-task hierarchies
  • User Analytics: Filter by user_id to see tasks from specific users
  • Multi-Agent Debugging: Use triggering_agent_id to trace agent-to-agent delegations
  • Performance Analysis: Track task completion times and status distribution

​
Notes

  • Tasks are returned in reverse chronological order (newest first)
  • Continuing a conversation by sending the same invocation id updates the same task/thread record instead of creating a new top-level task item
  • The title, result, and updated_at fields reflect the latest turn for that task/thread
  • The source_node_type indicates how the task was invoked (SDK, webhook, web UI, etc.)
  • Sub-tasks (when parent_task_id is set) represent work delegated to other agents
  • Use Get Task for the latest full task object and Get Task Thread or Get Task Thread (Full) for message history

​
See Also

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required

Query Parameters

​
page
integer
default:1

Page number (starting from 1)

Required range: x >= 1
​
per_page
integer
default:20

Items per page (max 50)

Required range: 1 <= x <= 50
​
user_id
string

Filter by user ID

​
parent_task_id
string

Filter by parent task ID

​
triggering_agent_id
string

Filter by triggering agent ID (parent calling agent)

​
status
enum<string>

Filter by task execution status

Available options:
pending,
executing,
paused,
error,
failed,
completed,
stopped
​
internal_status
string

Filter by internal task status

Response

Successful Response

​
items
TasksListItem · object[]
required
​
total
integer
required
​
page
integer
required
​
per_page
integer
required
​
total_pages
integer
required