# Pagination and filters

> The {data, next_cursor} envelope, limit and cursor, the filter[...] grammar and sort_by.

**What this is:** how every list reads — one envelope, one cursor, one filter grammar. **When you need it:** whenever you read more than one of anything.

**curl**


```bash
curl -G "$TASKSMATE_API_URL/v1/tasks" \
  -H "Authorization: Bearer $TASKSMATE_TOKEN" \
  --data-urlencode "org_id=$TASKSMATE_ORG" \
  --data-urlencode "filter[status]=in_progress,blocked" \
  --data-urlencode "sort_by=due_date" \
  --data-urlencode "limit=50"
```

**Python**


```python
page = tm.tasks.list(org_id="…", filter={"status": ["in_progress", "blocked"]},
                     sort_by="due_date", limit=50)
for task in page:          # follows next_cursor through every page
    print(task.task_id, task.title)
```

**tm**


```bash
tm tasks list --status in_progress --status blocked --sort-by due_date
```

Follow next\_cursor until it is null

## The envelope

Every list — 30 of them — answers `{"data": [...], "next_cursor": "…" | null}`. Pass `next_cursor` back as `cursor` until it is `null`. A page can be short, or even empty, while more follow: stop on `null`, not on a short page.

| Parameter | Meaning |
| --- | --- |
| `limit` | Page size, default 100; silently clamped to 1000. Default `100`. |
| `cursor` | Opaque token from the previous page's `next_cursor`. Only ever echo it back; `offset` is ignored when it is given. |
| `sort_by` | One of: task\_id, title, status, priority, due\_date, start\_date, created\_at, assignee, project\_id, priority\_rank, status\_rank, task\_type (400 otherwise). Default `title`. |
| `sort_order` | asc or desc (400 otherwise). Default `asc`. |

## Filters

Filters are repeated `filter[<key>]` parameters:

-   values are **OR** within a key (comma-separated or repeated);
-   keys are **AND**\-ed together;
-   an unknown key or value is a 400 that names it ([`invalid-parameter`](https://developers.tasksmate.indrasol.com/guides/errors/)).

The task list takes:

| Parameter | Meaning |
| --- | --- |
| `filter[status]` | Task status(es), comma-separated or repeated. |
| `filter[priority]` | Priority(ies), comma-separated or repeated. |
| `filter[assignee]` | Usernames, or `me` for the caller. |
| `filter[project]` | Project ids, or `__unfiled__` for tasks without a project (mixable). |
| `filter[tags]` | Tasks carrying any of these tags. |
| `filter[due_after]` | YYYY-MM-DD, inclusive. |
| `filter[due_before]` | YYYY-MM-DD, inclusive. |
| `filter[created_after]` | YYYY-MM-DD, inclusive. |
| `filter[created_before]` | YYYY-MM-DD, inclusive. |
| `filter[overdue]` | `true` → due before today and not completed. |
| `filter[search]` | Case-insensitive substring of the title, description, task id or any tag; `%`, `_`, `*`, `,` and `(` are matched literally. |
| `filter[search_fields]` | `all` (default) or `title` to match the title only. |
| `filter[team]` | Team ids, or `__none__` for tasks without a team (the two can be mixed). |
| `filter[task_type]` | One or more of `task`, `bug`, `agent`, comma-separated or repeated; any other value (including `goal`) is a 400. |

Other lists take the keys their [reference](https://developers.tasksmate.indrasol.com/reference/) page lists.

## Every list

-   [`organizations.list`](https://developers.tasksmate.indrasol.com/reference/operations/organizationslist/) GET /v1/organizations
-   [`projects.list`](https://developers.tasksmate.indrasol.com/reference/operations/projectslist/) GET /v1/projects/{org\_id}
-   [`tasks.list`](https://developers.tasksmate.indrasol.com/reference/operations/taskslist/) GET /v1/tasks
-   [`organization-members.list`](https://developers.tasksmate.indrasol.com/reference/operations/organization-memberslist/) GET /v1/organization-members/{org\_id}
-   [`organization-invites.list`](https://developers.tasksmate.indrasol.com/reference/operations/organization-inviteslist/) GET /v1/organization-invites/org/{org\_id}
-   [`organization-invites.mine`](https://developers.tasksmate.indrasol.com/reference/operations/organization-invitesmine/) GET /v1/organization-invites/user
-   [`designations.list`](https://developers.tasksmate.indrasol.com/reference/operations/designationslist/) GET /v1/designations
-   [`project-members.list`](https://developers.tasksmate.indrasol.com/reference/operations/project-memberslist/) GET /v1/project-members
-   [`project-resources.list`](https://developers.tasksmate.indrasol.com/reference/operations/project-resourceslist/) GET /v1/project-resources
-   [`task-attachments.list`](https://developers.tasksmate.indrasol.com/reference/operations/task-attachmentslist/) GET /v1/task-attachments
-   [`task-comments.list`](https://developers.tasksmate.indrasol.com/reference/operations/task-commentslist/) GET /v1/task-comments
-   [`task-history.list`](https://developers.tasksmate.indrasol.com/reference/operations/task-historylist/) GET /v1/task-history
-   [`service-accounts.list`](https://developers.tasksmate.indrasol.com/reference/operations/service-accountslist/) GET /v1/organizations/{org\_id}/service-accounts
-   [`tokens.list`](https://developers.tasksmate.indrasol.com/reference/operations/tokenslist/) GET /v1/tokens
-   [`webhooks.events`](https://developers.tasksmate.indrasol.com/reference/operations/webhooksevents/) GET /v1/webhooks/events
-   [`webhooks.list`](https://developers.tasksmate.indrasol.com/reference/operations/webhookslist/) GET /v1/webhooks
-   [`webhooks.deliveries`](https://developers.tasksmate.indrasol.com/reference/operations/webhooksdeliveries/) GET /v1/webhooks/{subscription\_id}/deliveries
-   [`oauth-clients.list`](https://developers.tasksmate.indrasol.com/reference/operations/oauth-clientslist/) GET /v1/oauth/clients
-   [`connected-apps.list`](https://developers.tasksmate.indrasol.com/reference/operations/connected-appslist/) GET /v1/me/connected-apps
-   [`sections.list`](https://developers.tasksmate.indrasol.com/reference/operations/sectionslist/) GET /v1/sections
-   [`teams.list`](https://developers.tasksmate.indrasol.com/reference/operations/teamslist/) GET /v1/teams
-   [`teams.list_tasks`](https://developers.tasksmate.indrasol.com/reference/operations/teamslist_tasks/) GET /v1/teams/{team\_id}/intake
-   [`sprints.list`](https://developers.tasksmate.indrasol.com/reference/operations/sprintslist/) GET /v1/teams/{team\_id}/sprints
-   [`milestones.list`](https://developers.tasksmate.indrasol.com/reference/operations/milestoneslist/) GET /v1/teams/{team\_id}/milestones
-   [`roadmap.task_stops`](https://developers.tasksmate.indrasol.com/reference/operations/roadmaptask_stops/) GET /v1/tasks/{task\_id}/roadmap
-   [`goals.list`](https://developers.tasksmate.indrasol.com/reference/operations/goalslist/) GET /v1/projects/{project\_id}/goals
-   [`audit.list`](https://developers.tasksmate.indrasol.com/reference/operations/auditlist/) GET /v1/audit
-   [`views.list`](https://developers.tasksmate.indrasol.com/reference/operations/viewslist/) GET /v1/views
-   [`views.rows`](https://developers.tasksmate.indrasol.com/reference/operations/viewsrows/) GET /v1/views/{view\_id}/rows
-   [`view-pins.list`](https://developers.tasksmate.indrasol.com/reference/operations/view-pinslist/) GET /v1/view-pins

---
Source: https://developers.tasksmate.indrasol.com/guides/pagination-and-filters/