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

# Pagination in The Stats API

> List endpoints return paginated results. Learn how to use page, per_page, the limit alias, and the meta object.

List endpoints return paginated results instead of one large payload. Paginated responses wrap results in `data` and include a `meta` object with the current page, page size, total record count, and total page count.

## Query parameters

| Parameter  | Type    | Default           | Description                                                                           |
| ---------- | ------- | ----------------- | ------------------------------------------------------------------------------------- |
| `page`     | integer | `1`               | Page number to retrieve.                                                              |
| `per_page` | integer | `20`              | Number of results per page. Maximum is `100`.                                         |
| `limit`    | integer | endpoint-specific | Alias for page size on endpoints that list it in the reference, such as match search. |

Prefer `per_page` for consistency. Use `limit` only on endpoints where it is documented in that endpoint's parameter table.

## Response format

```json theme={null}
{
  "data": [],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}
```

| Field              | Type    | Description                              |
| ------------------ | ------- | ---------------------------------------- |
| `meta.page`        | integer | Current page number.                     |
| `meta.per_page`    | integer | Number of results returned on this page. |
| `meta.total`       | integer | Total records across all pages.          |
| `meta.total_pages` | integer | Total pages at the current page size.    |

## Iterating through pages

```python theme={null}
import os
import requests

API_KEY = os.environ["STATS_API_KEY"]
BASE_URL = "https://api.thestatsapi.com/api"
headers = {"Authorization": f"Bearer {API_KEY}"}

page = 1
all_competitions = []

while True:
    response = requests.get(
        f"{BASE_URL}/football/competitions",
        headers=headers,
        params={"page": page, "per_page": 100},
    )
    response.raise_for_status()
    payload = response.json()

    all_competitions.extend(payload["data"])

    meta = payload["meta"]
    if page >= meta["total_pages"]:
        break

    page += 1

print(f"Fetched {len(all_competitions)} competitions")
```

<Tip>
  Set `per_page=100` when fetching large datasets to reduce request count.
</Tip>

<Note>
  The maximum allowed value for `per_page` is `100`. Requests with a higher value return `400 invalid_request`.
</Note>