# List tasks

> List tasks in a project

- Source: https://www.taskade.com/docs/actions/list-tasks
- Section: Action API
- Endpoint: `POST /listTasks` (API v2)
- Index of all pages: https://www.taskade.com/docs/llms.txt

## POST `/listTasks`

List tasks in a project

Base URL: `https://www.taskade.com/api/v2`

### Authentication

Send a personal access token or an OAuth 2.0 access token as a bearer token. Create a personal access token at [taskade.com/settings/api](https://www.taskade.com/settings/api).

```http
Authorization: Bearer tskdp_your_token_here
```

### Request body

`application/json`

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `projectId` | `string` | Yes | The project ID to list tasks for |
| `limit` | `number` | No | — |
| `after` | `string` | No | Cursor: task ID to get tasks after (do not combine with before) |
| `before` | `string` | No | Cursor: task ID to get tasks before (do not combine with after) |
| `completed` | `boolean` | No | Set false to list only open tasks, or true to list only completed ones. Leave it out to list both. The filter reads each task's own flag, and the cursors and `limit` apply to the filtered list. |

### Example request

```bash
curl -X POST "https://www.taskade.com/api/v2/listTasks" \
  -H "Authorization: Bearer $TASKADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"<projectId>"}'
```

### Responses

#### `200` — Default response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `ok` | `boolean` | Yes | — |
| `items` | `object[]` | Yes | — |
| `items[].id` | `string` | Yes | — |
| `items[].text` | `string` | Yes | — |
| `items[].parentId` | `string` | No | — |
| `items[].completed` | `boolean` | Yes | — |

A nested field marked Yes is required whenever its parent object is present.

### Errors

Errors return an `ok: false` envelope. Rate limiting returns `429` with `x-rate-limit-limit`, `x-rate-limit-remaining` and `x-rate-limit-reset` headers. `x-rate-limit-reset` is the number of seconds until the window reopens. `Retry-After` is not sent, so schedule retries from `x-rate-limit-reset`; retrying sooner will fail again.

```json
{ "ok": false, "message": "Unauthorized", "code": "UNAUTHORIZED" }
```

Rate limits for this version: enforced per endpoint; ceilings are not published and can change without notice. A `429` response carries `x-rate-limit-limit`, `x-rate-limit-remaining`, and `x-rate-limit-reset` (seconds until the window reopens). Back off from those headers rather than hardcoding numbers. If you need sustained throughput, prefer batching (operations like `/createTask` accept arrays) over tightening polling loops. See [Rate limits](https://www.taskade.com/docs/getting-started/action-api-guide#rate-limits).