Documentation / Guides
FOOTBALL API PAGINATION
PaginationLong lists come a page at a time. Walk them by page number, or by the cursor each page hands you.
WHICH ENDPOINTS PAGE
Lists come a page at a time, 100 rows unless you ask for up to 1,000: /v1/competitions/{competition}/seasons/{season}/matches, /v1/matches, /v1/results, /v1/fixtures, /v1/clubs, /v1/clubs/{club_id}/matches, /v1/grounds. Every other endpoint answers in one go.
THE PARAMETERS
pageintegerWhich page, from 1.per_pageintegerRows on a page, from 1 to 1,000. Default 100.cursorstringmeta.next_cursor from the page before, passed back unchanged, where the list offers one.WHAT META SAYS
countintegerRows on this page.pageintegerThis page.per_pageintegerRows a page.totalintegerRows on every page together.total_pagesintegerHow many pages.next_pageinteger or nullThe next page, or null on the last.prev_pageinteger or nullThe page before, or null on the first.next_cursorstring or nullPass it back as cursor for the next page; null when there is no more.WALKING A WHOLE SEASON
The cursor is the quicker way through a long run, such as every Premier League result of 2025/26. Pass it back exactly as it came; a cursor we did not give out answers 400 bad_request.
import requests
url = "https://api.footballapi.org/v1/results"
params = {"competition": "premier-league", "date_from": "2025-07-01", "date_to": "2026-06-30", "per_page": 1000}
rows = []
while True:
j = requests.get(url, params=params, headers={"X-API-Key": "your key"}).json()
rows += j["data"]
if not j["meta"].get("next_cursor"):
break
params = {"cursor": j["meta"]["next_cursor"], "per_page": 1000}
print(len(rows), "results")const url = new URL("https://api.footballapi.org/v1/results");
let params = { competition: "premier-league", date_from: "2025-07-01", date_to: "2026-06-30", per_page: 1000 };
const rows = [];
while (true) {
url.search = new URLSearchParams(params);
const j = await (await fetch(url, { headers: { "X-API-Key": "your key" } })).json();
rows.push(...j.data);
if (!j.meta.next_cursor) break;
params = { cursor: j.meta.next_cursor, per_page: 1000 };
}
console.log(rows.length, "results");Each page is one call against your limits. A season of a top flight is a few hundred matches, one page at 1,000 a page.