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": "04dbe342-27ef-4fcb-bc16-f19457e892b3",
      "agent_id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
      "status": "completed",
      "created_at": "2026-02-07T06:18:48.201887Z",
      "updated_at": "2026-02-07T06:18:56.118239Z",
      "result": "To reset your password, visit the login page and click 'Forgot Password'.",
      "title": "how to reset the password",
      "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
      "parent_task_id": null
    },
    {
      "id": "9c97a223-cb0c-41ea-91b0-5e4c5e76f40b",
      "agent_id": "93a1cd50-2af0-452a-99a0-6e1f1b14fb29",
      "status": "completed",
      "created_at": "2026-02-07T05:46:12.806507Z",
      "updated_at": "2026-02-07T05:46:36.199565Z",
      "result": "Our product offers three key benefits: automated deployment, multi-framework support, and enterprise security.",
      "title": "explain product benefits",
      "organization_id": "91fbe9bc-35b3-41e8-b59d-922fb5a0f031",
      "parent_task_id": null
    }
  ],
  "total": 39,
  "page": 1,
  "per_page": 20,
  "total_pages": 2
}
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

​
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

Response

Successful Response

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