# Pagination

Cursor pagination with limit, starting_after and ending_before.



Every list returns newest first, in this envelope:

```json
{ "object": "list", "data": [ { "object": "team", "id": "team_…" } ], "has_more": true }
```

## Parameters [#parameters]

| Parameter        | What it does                                                              |
| ---------------- | ------------------------------------------------------------------------- |
| `limit`          | How many objects to return, 1 to 100. Default 20.                         |
| `starting_after` | An object id from the previous page: return the objects after it (older). |
| `ending_before`  | An object id: return the objects before it (newer).                       |

Use one cursor at a time. Pages are positioned by each object's creation time and id, so objects
created or deleted between two calls never make a page skip or repeat anything.

## Reading every page [#reading-every-page]

```bash
curl "https://api-hq.aiworkforceone.com/v1/teams?limit=100" -H "Authorization: Bearer $HQ_API_KEY"
# then, while has_more is true:
curl "https://api-hq.aiworkforceone.com/v1/teams?limit=100&starting_after=team_LAST_ID" \
  -H "Authorization: Bearer $HQ_API_KEY"
```

## Filters [#filters]

Some lists take filters, for example `GET /v1/sessions?team=team_…&status=running` or
`GET /v1/audit_events?created[gte]=2026-11-01T00:00:00Z`. Each endpoint lists its filters in the
[reference](/docs/api/reference/).

A parameter a list does not know is an error, not ignored: `400 invalid_request`, with
`errors[0].field` naming it. A typo can never silently return a wider list.

A `created[gte]` or `created[lte]` value must be an RFC 3339 timestamp with a year from 0001 to
9999\. Anything else, year 0000 included, is `400 invalid_request` with `errors[0].code`
`invalid_value` and `errors[0].field` naming the parameter, for example `created[lte]`.

## Lists that page forward only [#lists-that-page-forward-only]

The audit log, schedule runs and invoices take `starting_after` only.
