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

> List tasks for an agent or a user.

`Tasks.alist` returns task summaries for a given agent. `Tasks.alist_user_tasks` does the same scoped to a single end-user across all agents.

```python theme={"dark"}
from xpander_sdk import Tasks

tasks = Tasks()
items = await tasks.alist(agent_id="agent-123")
for item in items:
    print(item.id, item.status.value, item.title or "(no title)")
```

### Parameters

| Parameter  | Type   | Required | Default | Description                                                                                                     |
| ---------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `agent_id` | `str`  | Yes      | –       | Agent whose tasks to list.                                                                                      |
| `filters`  | `dict` | No       | `None`  | Query filters. Supported keys: `user_id`, `parent_task_id`, `triggering_agent_id`, `status`, `internal_status`. |

### Returns `list[TasksListItem]`

| Field                 | Type                   | Description                                    |
| --------------------- | ---------------------- | ---------------------------------------------- |
| `id`                  | `str`                  | Task ID.                                       |
| `agent_id`            | `str`                  | Owning agent.                                  |
| `user_id`             | `str \| None`          | End-user the task was created for.             |
| `parent_task_id`      | `str \| None`          | If this is a sub-task.                         |
| `triggering_agent_id` | `str \| None`          | If this task was kicked off by another agent.  |
| `organization_id`     | `str`                  | Owning org.                                    |
| `status`              | `AgentExecutionStatus` | Current status.                                |
| `created_at`          | `datetime \| None`     | Creation timestamp.                            |
| `updated_at`          | `datetime \| None`     | Last-update timestamp.                         |
| `source_node_type`    | `str \| None`          | Trigger origin (`webhook`, `slack`, `sdk`, …). |
| `result`              | `str \| None`          | Final result if completed.                     |
| `title`               | `str \| None`          | Task title.                                    |

To load the full `Task` (including input, files, deep-planning state, tokens, activity log access), call `.aload()` on the item or pass `item.id` to `tasks.aget()`.

## Examples

### Filter by status

```python theme={"dark"}
from xpander_sdk import AgentExecutionStatus

failed = await tasks.alist(
    agent_id="agent-123",
    filters={"status": AgentExecutionStatus.Failed.value},
)
```

The `status` filter accepts the lowercase string value: `"pending"`, `"executing"`, `"completed"`, `"failed"`, etc.

### Filter by end-user

```python theme={"dark"}
mine = await tasks.alist(
    agent_id="agent-123",
    filters={"user_id": "user_42"},
)
```

### Tasks for a user

`alist_user_tasks` searches across every agent the user has interacted with:

```python theme={"dark"}
items = await tasks.alist_user_tasks(user_id="user_42")
```

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `user_id` | `str`  | Yes      | End-user identifier.                        |
| `filters` | `dict` | No       | Same filter keys as above, minus `user_id`. |

### Sync versions

```python theme={"dark"}
items = tasks.list(agent_id="agent-123")
items = tasks.list_user_tasks(user_id="user_42")
```

## Errors

Raises [`ModuleException`](/developers/sdk-reference/error-handling) on failure. Common statuses:

| Status    | Cause                                         |
| --------- | --------------------------------------------- |
| 401 / 403 | Auth failure or wrong organization.           |
| 404       | Agent doesn't exist (or you can't access it). |
| 500       | Server error.                                 |