> ## Documentation Index
> Fetch the complete documentation index at: https://help.nops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How list endpoints paginate results with cursors

# Pagination

All list endpoints return a consistent envelope: an array of results in `data`
and a `pagination` object describing how to fetch the next page.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    { "id": "..." }
  ],
  "pagination": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJvZmZzZXQiOjUwfQ"
  }
}
```

## Parameters

| Query param | Description                                                                                   |
| ----------- | --------------------------------------------------------------------------------------------- |
| `limit`     | Maximum number of items to return. Between `1` and `200`. Defaults to `50`.                   |
| `cursor`    | Opaque cursor from the previous response's `pagination.next_cursor`. Omit for the first page. |

## Pagination object

| Field         | Description                                                                            |
| ------------- | -------------------------------------------------------------------------------------- |
| `limit`       | The page size applied to this response.                                                |
| `has_more`    | `true` when more results are available.                                                |
| `next_cursor` | Pass this as `cursor` to fetch the next page, or `null` when you have reached the end. |

## Iterating all pages

Keep requesting with the returned `next_cursor` until `has_more` is `false`
(equivalently, until `next_cursor` is `null`).

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# First page
curl -H "Authorization: Bearer $NOPS_API_KEY" \
  "https://api.nops.io/v1/reports?limit=50"

# Next page — pass the cursor from the previous response
curl -H "Authorization: Bearer $NOPS_API_KEY" \
  "https://api.nops.io/v1/reports?limit=50&cursor=eyJvZmZzZXQiOjUwfQ"
```

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function fetchAll(path) {
  const results = [];
  let cursor = null;

  do {
    const url = new URL(`https://api.nops.io${path}`);
    url.searchParams.set('limit', '200');
    if (cursor) url.searchParams.set('cursor', cursor);

    const res = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.NOPS_API_KEY}` },
    });
    const body = await res.json();

    results.push(...body.data);
    cursor = body.pagination.next_cursor;
  } while (cursor);

  return results;
}
```

## Notes

* Treat `next_cursor` as opaque — do not parse or construct it yourself. Its
  encoding may change without notice.
* Some list endpoints include an extra `meta` object alongside `data` and
  `pagination` (for example, `scope_counts` on reports). `data` and
  `pagination` are always present on list responses.