Pagination in The Stats API - The Stats API

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

{
  "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

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")

Set per_page=100 when fetching large datasets to reduce request count.

The maximum allowed value for per_page is 100. Requests with a higher value return 400 invalid_request.