> ## Documentation Index
> Fetch the complete documentation index at: https://docs.get-spotlight.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pagination

> How paging works across list endpoints.

## Query parameters

All list endpoints accept these two query parameters:

<ParamField query="limit" default="varies" type="integer">
  Number of items to return per page. Must be a positive integer. Capped at **500**.
</ParamField>

<ParamField query="page" default="1" type="integer">
  1-based page index.
</ParamField>

## Paging response object

Paginated endpoints return a `paging` object alongside the `data` array:

```json theme={null}
{
  "data": [...],
  "paging": {
    "page": 1,
    "limit": 50,
    "total": 214,
    "nextPage": 2
  }
}
```

| Field      | Type            | Description                                           |
| ---------- | --------------- | ----------------------------------------------------- |
| `page`     | integer         | Current page number.                                  |
| `limit`    | integer         | Effective limit used for this response.               |
| `total`    | integer \| null | Total matching rows. May be `null` on some endpoints. |
| `nextPage` | integer \| null | Next page number, or `null` if this is the last page. |

## Walking all pages

```python theme={null}
import requests

BASE_URL = "https://app.get-spotlight.com/api"
HEADERS  = {"x-spotlight-api-key": "YOUR_API_KEY"}

page, results = 1, []
while True:
    r = requests.get(
        f"{BASE_URL}/v1/runs/RUN_ID",
        headers=HEADERS,
        params={"limit": 500, "page": page},
    ).json()
    results.extend(r["data"])
    if r["paging"]["nextPage"] is None:
        break
    page += 1
```

## Internal limits

The database enforces a hard **2000-row** cap per query. For heavy endpoints like `/sources`, the API fetches data in internal batches and merges results before responding — you do not need to handle this yourself.