Pagination

listMatches returns up to 200 matches per call. When the result set exceeds your limit, the response carries a next_cursor field. Pass it back as ?after= to get the next page.

Why cursors?

Cursors are stable across data mutations — new matches inserted between your calls do not shift older pages, the way an ?offset= parameter would. That guarantee matters here because matches are created continuously.

Walkthrough

import requests

def fetch_all(filters: dict, key: str, page_size: int = 200):
    base = "https://api.scorelytics.pro/v1/football/matches"
    cursor = None
    while True:
        params = {**filters, "limit": page_size}
        if cursor is not None:
            params["after"] = cursor
        r = requests.get(base, params=params, headers={"X-API-Key": key})
        r.raise_for_status()
        body = r.json()
        yield from body["data"]
        cursor = body.get("next_cursor")
        if cursor is None:
            return

for m in fetch_all({"league_id": "LaLigaID"}, "sk_live_..."):
    print(m["id"], m["home_team"], "-", m["away_team"])

Stop conditions

Two reliable signals that you're done:

1. next_cursor is missing or null.
2. data is empty.

Either is sufficient. We recommend treating either as the terminator.

Maximum page size

limit accepts values up to 200. Larger values are clamped silently. For interactive UI listings, 20–50 is usually right; for back-fill jobs, go to 200.

Sort order

Results are sorted by kickoff_ts ascending. Pages are contiguous in that order. If you need descending, reverse client-side.