Pagination and sorting

Use this page to fetch long lists one page at a time and get results in the order you want.

Fastest way: ask your AI. Set up your coding tool once with Build with AI, then paste:

Using TheStatsAPI (reference: https://api.thestatsapi.com/llms.txt), write a server-side helper that fetches every page of /football/matches for competition_id=comp_3039 and season_id=sn_8406098 with per_page=100, stopping at meta.total_pages.

Which endpoints are paginated

Endpoint	Default page size	Maximum
`GET /football/competitions`	20	100
`GET /football/teams`	20	100
`GET /football/players`	20	100
`GET /football/matches`	20	100
`GET /coverage/leagues`	100	200

Other endpoints that return lists, such as seasons, squads, standings and timelines, return everything in one response. They don’t accept page or per_page: sending them returns 400 UNKNOWN_PARAMETER.

Parameters

Parameter	Default	What it does
`page`	`1`	The page to return, starting at 1.
`per_page`	`20` (`100` on `/coverage/leagues`)	Results per page. Over the maximum returns `400 BAD_REQUEST`, for example `per_page cannot exceed 100`.
`limit`		Older name for `per_page`. Use `per_page` in new code.

page and per_page must be positive whole numbers. 0 or a negative number returns 400 BAD_REQUEST.

The `meta` object

Paginated responses put results in data and page details in meta:

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 204,
    "total_pages": 11
  }
}

Field	Meaning
`page`	The page you asked for.
`per_page`	The page size you asked for. The last page can hold fewer results.
`total`	Results across all pages.
`total_pages`	Pages at this page size. `0` when there are no results.

Past the last page

Endpoint	What you get
`/football/matches`	`400 PAGE_OUT_OF_RANGE`, for example `page 999 is out of range (total_pages=5)`.
All other paginated endpoints	`200` with an empty `data` array. `meta` still shows the real `total` and `total_pages`.

Either way, stop when page reaches meta.total_pages.

Loop through every page

Ask for per_page=100 so you make fewer requests. Every page counts toward your rate limits.

const BASE_URL = "https://api.thestatsapi.com/api";
const headers = { Authorization: `Bearer ${process.env.THESTATSAPI_API_KEY}` };

async function fetchAllPages(path, params = {}) {
  const results = [];
  let page = 1;

  while (true) {
    const query = new URLSearchParams({ ...params, page: String(page), per_page: "100" });
    const res = await fetch(`${BASE_URL}${path}?${query}`, { headers });
    if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);

    const { data, meta } = await res.json();
    results.push(...data);

    if (page >= meta.total_pages) break;
    page += 1;
  }

  return results;
}

const matches = await fetchAllPages("/football/matches", {
  competition_id: "comp_3039",
  season_id: "sn_8406098",
});
console.log(`Fetched ${matches.length} matches`);

import os
import requests

BASE_URL = "https://api.thestatsapi.com/api"
HEADERS = {"Authorization": f"Bearer {os.environ['THESTATSAPI_API_KEY']}"}

def fetch_all_pages(path, params=None):
    results = []
    page = 1

    while True:
        query = {**(params or {}), "page": page, "per_page": 100}
        res = requests.get(f"{BASE_URL}{path}", headers=HEADERS, params=query)
        res.raise_for_status()

        body = res.json()
        results.extend(body["data"])

        if page >= body["meta"]["total_pages"]:
            break
        page += 1

    return results

matches = fetch_all_pages(
    "/football/matches",
    {"competition_id": "comp_3039", "season_id": "sn_8406098"},
)
print(f"Fetched {len(matches)} matches")

Filter before you page. Narrowing /football/matches with competition_id, season_id, team_id or date_from and date_to is cheaper than paging through everything and filtering in your code.

Default order and sorting

Endpoint	Default order	Change it with
`/football/matches`	Newest kickoff first (`sort=-utc_date`). Upcoming fixtures come before results.	`sort=utc_date` for soonest first.
`/football/competitions`, `/football/teams`, `/football/players`	With `search`: best match first. Without `search`: A to Z by name.	`sort=name` for A to Z.

On /football/matches, matches with the same kickoff time are ordered by match ID, so pages don’t shuffle between requests. Two common recipes:

curl "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&status=scheduled&sort=utc_date&per_page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://api.thestatsapi.com/api/football/matches?team_id=tm_9145&status=finished&per_page=1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Because the default order puts the furthest-away fixtures first, a plain ?team_id=tm_9145&per_page=1 returns a match weeks away, not the next one. Add status and sort as shown above.

Next steps

Fixtures and results: more recipes for filtering and sorting matches.
Rate limits: every page is one request, so plan your budget.
Errors: what PAGE_OUT_OF_RANGE and other codes mean.

Get started

Guides

Core concepts

Pagination and sorting

Which endpoints are paginated

Parameters

The `meta` object

Past the last page

Loop through every page

Default order and sorting

Next steps

Which endpoints are paginated

Parameters

The meta object

Past the last page

Loop through every page

Default order and sorting

Next steps

The `meta` object