> ## 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 Agent Tasks

> Retrieve paginated list of task executions for a specific agent with optional filters

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

<ParamField path="agent_id" type="string" required>
  Unique identifier of the agent (UUID format)
</ParamField>

## Query Parameters

<ParamField query="page" type="integer" default={1}>
  Page number (starting from 1)
</ParamField>

<ParamField query="per_page" type="integer" default={20}>
  Items per page (maximum 50)
</ParamField>

<ParamField query="user_id" type="string">
  Filter by user ID who created the task
</ParamField>

<ParamField query="parent_task_id" type="string">
  Filter by parent task ID (for sub-tasks)
</ParamField>

<ParamField query="triggering_agent_id" type="string">
  Filter by triggering agent ID (parent calling agent in multi-agent workflows)
</ParamField>

<ParamField query="status" type="string">
  Filter by task execution status: `pending`, `executing`, `paused`, `error`, `failed`, `completed`, `stopped`
</ParamField>

<ParamField query="internal_status" type="string">
  Filter by internal task processing status
</ParamField>

## Response

<ResponseField name="items" type="array">
  Array of task objects

  <Expandable title="Task Object">
    <ResponseField name="id" type="string">
      Unique identifier for the task (UUID format)
    </ResponseField>

    <ResponseField name="agent_id" type="string">
      ID of the agent that executed this task
    </ResponseField>

    <ResponseField name="user_id" type="string">
      ID of the user who created the task (nullable)
    </ResponseField>

    <ResponseField name="parent_task_id" type="string">
      ID of parent task if this is a subtask (nullable)
    </ResponseField>

    <ResponseField name="triggering_agent_id" type="string">
      ID of agent that triggered this task (nullable)
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      Organization UUID this task belongs to
    </ResponseField>

    <ResponseField name="status" type="string">
      Current task status: `pending`, `executing`, `paused`, `error`, `failed`, `completed`, or `stopped`
    </ResponseField>

    <ResponseField name="source_node_type" type="string">
      Source of task invocation: sdk, webhook, assistant, etc.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO timestamp of task creation
    </ResponseField>

    <ResponseField name="updated_at" type="string">
      ISO timestamp of last update
    </ResponseField>

    <ResponseField name="title" type="string">
      Task title or the latest input text for that task/thread
    </ResponseField>

    <ResponseField name="result" type="string">
      Latest result for that task/thread (nullable, present when completed)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of tasks for this agent
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="per_page" type="integer">
  Number of items per page
</ResponseField>

<ResponseField name="total_pages" type="integer">
  Total number of pages available
</ResponseField>

## Example Requests

### List all tasks for an agent

```bash theme={"dark"}
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

```bash theme={"dark"}
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

```bash theme={"dark"}
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

```json theme={"dark"}
{
  "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](/api-reference/v1/tasks/get-task) for the latest full task object and [Get Task Thread](/api-reference/v1/tasks/get-thread) or [Get Task Thread (Full)](/api-reference/v1/tasks/get-thread-full) for message history

## See Also

* [List Tasks](/api-reference/v1/tasks/list-tasks) - List all tasks across all agents
* [Get Task](/api-reference/v1/tasks/get-task) - Get detailed information about a specific task
* [Invoke Agent](/api-reference/v1/agents/invoke-async) - Create new tasks


## OpenAPI

````yaml GET /v1/agents/{agent_id}/tasks
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 <jwt>`).
        
  version: '0.001'
servers:
  - url: https://api.xpander.ai
security: []
paths:
  /v1/agents/{agent_id}/tasks:
    get:
      tags:
        - API v1
        - Agents
        - Tasks CRUD
      summary: Get Agent Tasks
      description: >-
        Retrieve paginated list of task executions for a specific agent with
        optional filters
      operationId: Get_Agent_Tasks_v1_agents__agent_id__tasks_get
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number (starting from 1)
            default: 1
            title: Page
          description: Page number (starting from 1)
        - name: per_page
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Items per page (max 50)
            default: 20
            title: Per Page
          description: Items per page (max 50)
        - name: user_id
          in: query
          required: false
          schema:
            type: string
            description: Filter by user ID
            title: User Id
          description: Filter by user ID
        - name: parent_task_id
          in: query
          required: false
          schema:
            type: string
            description: Filter by parent task ID
            title: Parent Task Id
          description: Filter by parent task ID
        - name: triggering_agent_id
          in: query
          required: false
          schema:
            type: string
            description: Filter by triggering agent ID (parent calling agent)
            title: Triggering Agent Id
          description: Filter by triggering agent ID (parent calling agent)
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AgentExecutionStatus-Input'
            description: Filter by task execution status
          description: Filter by task execution status
        - name: internal_status
          in: query
          required: false
          schema:
            type: string
            description: Filter by internal task status
            title: Internal Status
          description: Filter by internal task status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse_TasksListItem_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    AgentExecutionStatus-Input:
      type: string
      enum:
        - pending
        - executing
        - paused
        - error
        - failed
        - completed
        - stopped
      title: AgentExecutionStatus
    PaginatedResponse_TasksListItem_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/TasksListItem'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        page:
          type: integer
          title: Page
        per_page:
          type: integer
          title: Per Page
        total_pages:
          type: integer
          title: Total Pages
      type: object
      required:
        - items
        - total
        - page
        - per_page
        - total_pages
      title: PaginatedResponse[TasksListItem]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    TasksListItem:
      properties:
        id:
          type: string
          title: Id
          description: Unique identifier for this execution
        agent_id:
          type: string
          title: Agent Id
          description: ID of the agent being executed
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: ID of the user that created the task
        parent_task_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Parent Task Id
          description: ID of the parent task that triggered this task
        triggering_agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Triggering Agent Id
          description: ID of the triggering agen that triggered this task
        organization_id:
          type: string
          title: Organization Id
          description: ID of the organization that owns the agent
        status:
          $ref: >-
            #/components/schemas/xpander_sdk__modules__tasks__models__task__AgentExecutionStatus
          description: Current execution status
        created_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Created At
          description: Timestamp when the execution was created
        updated_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Updated At
          description: Timestamp of the last update to this execution
        source_node_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Node Type
          description: Type of the source node that triggered this execution (if any)
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
          description: Final result of the execution, if available
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: Task title
      type: object
      required:
        - id
        - agent_id
        - organization_id
        - status
      title: TasksListItem
      description: >-
        Summary representation of a task in list operations.


        This model provides essential information about a task, suitable for

        display and interaction in list views, while enabling efficient
        retrieval

        of full task details when needed.


        Attributes:
            id (str): Unique identifier for this task execution.
            agent_id (str): ID of the agent responsible for executing the task.
            organization_id (str): ID of the organization that owns the agent.
            status (AgentExecutionStatus): Current execution status of the task.
            created_at (Optional[datetime]): Timestamp when the execution was created.
            updated_at (Optional[datetime]): Timestamp of the last update to this execution.
            source_node_type (Optional[str]): The type of the source node that triggered execution.
            result (Optional[str]): Final result of the execution, if available.
            title (Optional[str]): Task title.

        Methods:
            aload: Asynchronously load the full task details.
            load: Synchronously load the full task details.

        Example:
            >>> tasks = Tasks()
            >>> task_list = tasks.list(agent_id="agent123")
            >>> for item in task_list:
            ...     print(f"Task: {item.id} - Status: {item.status}")
            ...     full_task = item.load()  # Load complete task details
    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
    xpander_sdk__modules__tasks__models__task__AgentExecutionStatus:
      type: string
      enum:
        - pending
        - executing
        - paused
        - error
        - failed
        - completed
        - stopped
      title: AgentExecutionStatus
      description: |-
        Enumeration of possible execution statuses for an agent task.

        Values:
            Pending: Task is pending execution.
            Executing: Task is currently executing.
            Paused: Task execution is paused.
            Error: Task encountered an error during execution.
            Failed: Task execution failed to complete successfully.
            Completed: Task execution completed successfully.
            Stopped: Task execution was stopped by the user.

        Example:
            >>> status = AgentExecutionStatus.Executing
            >>> print(status.value)  # "executing"
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      description: API Key for authentication
      in: header
      name: x-api-key

````