# Pagination

Most lists return everything in one response; test runs page with a cursor, secret versions with before, and two lists are capped.

Most list endpoints return every matching object in one response, in a fixed order. Two lists page,
each in its own way, and two return only the newest items. There is no shared `limit` parameter.

## Lists that page

| List                                                   | Page size                  | How to get the next page                                                                        |
| ------------------------------------------------------ | -------------------------- | ----------------------------------------------------------------------------------------------- |
| [List test runs](https://docs.qa.clankership.net/api/test-runs/list.md)                  | 50 runs, newest first      | Send the response's `nextCursor` as `cursor`. `nextCursor` is `null` on the last page           |
| [List a secret's versions](https://docs.qa.clankership.net/api/secrets/list-versions.md) | 100 versions, newest first | Send the oldest `version` you have as `before`. A page with fewer than 100 versions is the last |

Test runs, page by page. The response below is trimmed to the fields that matter here:

```bash
curl "https://api.clankertest.com/v1/workspaces/acme/test-runs?product=storefront" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

```json
{
  "runs": [{ "number": 1289, "state": "finished", "result": "passed" }],
  "nextCursor": 1240
}
```

```bash
curl "https://api.clankertest.com/v1/workspaces/acme/test-runs?product=storefront&cursor=1240" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

The cursor is a run number: the next page holds the runs numbered below it, so runs published while
you page do not shift the pages you have not read yet. Keep the same filters, such as `product`,
`result` or `commit`, on every page.

A secret's history in one environment:

```bash
curl "https://api.clankertest.com/v1/workspaces/acme/products/storefront/secrets/DATABASE_URL/environments/staging/versions?before=101" \
  -H "Authorization: Bearer $CLANKER_API_KEY"
```

The CLI takes the same parameter:
`clanker vault secret history --product storefront --env staging --name DATABASE_URL --before 101`.

## Lists that return the newest only

| List                                          | Returns                                             |
| --------------------------------------------- | --------------------------------------------------- |
| [List events](https://docs.qa.clankership.net/api/events/list.md)               | The workspace's 50 most recent events, newest first |
| [List notifications](https://docs.qa.clankership.net/api/notifications/list.md) | Your 100 newest notifications, newest first         |

Neither takes a cursor; older items are not available through the API.

## Lists that return everything

Every other list returns all matching objects at once. Narrow them with their filters instead of
paging:

| List                                                                        | Filters                                | Order                                            |
| --------------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------------ |
| [List tickets](https://docs.qa.clankership.net/api/tickets/list.md)                                           | `team`, `project`, `owner`, `category` | Status category, then status position, then rank |
| [List projects](https://docs.qa.clankership.net/api/projects/list.md)                                         | `team`, `product`, `archived`          | Priority order                                   |
| [List teams](https://docs.qa.clankership.net/api/teams/list.md)                                               | `archived`                             | Name                                             |
| [List products](https://docs.qa.clankership.net/api/products/list.md), [environments](https://docs.qa.clankership.net/api/environments/list.md) | `archived`                             | Name                                             |
| [List deployments](https://docs.qa.clankership.net/api/deployments/list.md)                                   | `product`, `environment`, `archived`   | Product name, then environment name              |
| [List ticket statuses](https://docs.qa.clankership.net/api/ticket-statuses/list.md), [tags](https://docs.qa.clankership.net/api/tags/list.md)   | `team`                                 | Board order; tags by name                        |
| [List agents](https://docs.qa.clankership.net/api/agents/list.md)                                             | `person`                               | Member's name, then client                       |
| [List members](https://docs.qa.clankership.net/api/members/list.md)                                           | None                                   | Name                                             |
| Views, comments, a ticket's messages, invites, keys and secrets             | None                                   | Each endpoint says                               |

Ticket lists leave out plans; [Get a ticket](https://docs.qa.clankership.net/api/tickets/get.md) returns one ticket with its plan.

## Not pagination

`before` and `after` on [Reorder a ticket](https://docs.qa.clankership.net/api/tickets/reorder.md),
[Reorder a project](https://docs.qa.clankership.net/api/projects/reorder.md) and [Reorder a ticket status](https://docs.qa.clankership.net/api/ticket-statuses/reorder.md)
name a position to move to, not a page.