> ## 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.

# List Tasks

> Get paginated list of tasks with optional filtering by status, agent, or date range

Retrieve a paginated list of tasks with optional filtering by status, agent ID, or creation date. Useful for monitoring task execution across your organization or for specific agents.

## 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="agent_id" type="string">
  Filter by specific agent UUID
</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 status: `pending`, `executing`, `paused`, `error`, `failed`, `completed`, `stopped`
</ParamField>

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

<ParamField query="from_date" type="string">
  Filter tasks created on or after this date (ISO 8601, e.g., `2026-02-01T00:00:00Z`)
</ParamField>

<ParamField query="to_date" type="string">
  Filter tasks created on or before this date (ISO 8601)
</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">
      UUID of the agent that executed this task
    </ResponseField>

    <ResponseField name="user_id" type="string">
      UUID of the user who created the task (null if created via API)
    </ResponseField>

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

    <ResponseField name="triggering_agent_id" type="string">
      UUID of agent that triggered this task (null if not triggered by agent)
    </ResponseField>

    <ResponseField name="organization_id" type="string">
      UUID of the organization that owns this task
    </ResponseField>

    <ResponseField name="status" type="string">
      Current task status: `queued`, `running`, `completed`, `failed`, `cancelled`
    </ResponseField>

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

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

    <ResponseField name="source_node_type" type="string">
      Source that created the task (e.g., `sdk`, `api`, `webhook`)
    </ResponseField>

    <ResponseField name="result" type="string">
      Task execution result as JSON string (present when completed)
    </ResponseField>

    <ResponseField name="title" type="string">
      Task title or description (nullable)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of tasks matching the filter across all pages
</ResponseField>

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

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

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

## Example Requests

```bash theme={"dark"}
# List all tasks (first page)
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks?page=1&per_page=10"

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

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

# Filter by date range
curl -X GET -H "x-api-key: <your-api-key>" \
  "https://api.xpander.ai/v1/tasks?from_date=2026-02-01T00:00:00Z&to_date=2026-02-07T23:59:59Z"
```

## Example Response

```json theme={"dark"}
{
  "items": [
    {
      "id": "81250b20-e9d7-4b3b-9995-07dc72b4bb59",
      "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "user_id": null,
      "parent_task_id": null,
      "triggering_agent_id": null,
      "organization_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "status": "completed",
      "created_at": "2026-02-07T02:13:27.228497Z",
      "updated_at": "2026-02-07T02:13:41.541072Z",
      "source_node_type": "sdk",
      "result": "{\"name\":\"xpander.ai\",\"notes\":\"Full-stack agent platform...\"}",
      "title": "What is xpander.ai?"
    }
  ],
  "total": 4300,
  "page": 1,
  "per_page": 2,
  "total_pages": 2150
}
```

## Use Cases

* **Monitor task volume** - Track total tasks and completion rates
* **Filter by agent** - See tasks for a specific agent
* **Find completed work** - Retrieve only successful task executions
* **Track recent activity** - Filter by creation date range

## See Also

* [Get Task](/api-reference/v1/tasks/get-task) - Get detailed information about a specific task
* [Stop Task](/api-reference/v1/tasks/stop-task) - Cancel a running task
* [Delete Task](/api-reference/v1/tasks/delete-task) - Permanently remove a task and its data
* [Get Task Thread](/api-reference/v1/tasks/get-thread) - Get the conversation history of a task


## OpenAPI

````yaml GET /v1/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/tasks:
    get:
      tags:
        - API v1
        - Tasks
        - Tasks CRUD
      summary: Get Tasks
      description: Get pagniated tasks list
      operationId: Get_Tasks_v1_tasks_get
      parameters:
        - 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 (optional)
            title: User Id
          description: filter by user id (optional)
        - name: parent_task_id
          in: query
          required: false
          schema:
            type: string
            description: filter by parent task id (optional)
            title: Parent Task Id
          description: filter by parent task id (optional)
        - name: agent_id
          in: query
          required: false
          schema:
            type: string
            description: filter by agent id (optional)
            title: Agent Id
          description: filter by agent id (optional)
        - name: triggering_agent_id
          in: query
          required: false
          schema:
            type: string
            description: filter by triggering agent id (parent calling agent) (optional)
            title: Triggering Agent Id
          description: filter by triggering agent id (parent calling agent) (optional)
        - name: status
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/AgentExecutionStatus-Input'
            description: filter by task status (optional)
          description: filter by task status (optional)
        - name: internal_status
          in: query
          required: false
          schema:
            type: string
            description: filter by internal status (optional)
            title: Internal Status
          description: filter by internal status (optional)
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: filter tasks created on or after this date (ISO 8601, optional)
            title: From Date
          description: filter tasks created on or after this date (ISO 8601, optional)
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: filter tasks created on or before this date (ISO 8601, optional)
            title: To Date
          description: filter tasks created on or before this date (ISO 8601, optional)
      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

````