Pagination

✅ Included in All Plans

Pagination is included at no additional cost.

Plans differ only in leagues and API call limits.

Compare plans →

This page explains how pagination works in the Sportmonks Football API v3 and how to walk through large result sets using cursor-based pagination.

Why pagination exists

Responses to broad requests can return thousands of results. Returning everything at once is slow and hard to work with. Instead, the API splits results into pages and gives you a cursor to move to the next one.

How cursor pagination works

Every paginated response includes a pagination object at the end of the response body:

"pagination": {
  "count": 2,
  "per_page": 2,
  "current_page": 1,
  "next_cursor": "WzEsMixbMTk3MTAxMDBdLFtbInNwb3J0cy5maXh0dXJlcy5pZCIsMV1dXQ",
  "has_more": true
}

Field	Description
count	Number of results in this page
per_page	Page size used in this request
current_page	Page number (always 1 for cursor-based requests)
next_cursor	Opaque string to pass in your next request
has_more	true if there are more results to fetch

First request

Make a standard request with no cursor. Use per_page to control how many results come back (range: 1-50, default: 25):

https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&order=desc&per_page=25

Subsequent requests

Take the next_cursor value from the response and pass it as a cursor parameter:

https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&order=desc&per_page=25&cursor=WzEsMixbMTk3MTAxMD...

Keep repeating this until has_more is false. At that point you have retrieved all available results.

Checking for more results

Always check has_more before making the next call. When it is false, there is no next_cursor to use:

"pagination": {
  "count": 14,
  "per_page": 25,
  "current_page": 1,
  "next_cursor": null,
  "has_more": false
}

Code examples

async function fetchAllFixtures(apiToken) {
  const baseUrl = 'https://api.sportmonks.com/v3/football/fixtures';
  let cursor = null;
  let allFixtures = [];

  do {
    const url = new URL(baseUrl);
    url.searchParams.set('api_token', apiToken);
    url.searchParams.set('order', 'desc');
    url.searchParams.set('per_page', '25');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url.toString());
    const data = await response.json();

    allFixtures = allFixtures.concat(data.data);
    cursor = data.pagination.has_more ? data.pagination.next_cursor : null;
  } while (cursor);

  return allFixtures;
}

function fetchAllFixtures(string $apiToken): array {
    $baseUrl = 'https://api.sportmonks.com/v3/football/fixtures';
    $cursor = null;
    $allFixtures = [];

    do {
        $params = [
            'api_token' => $apiToken,
            'order'     => 'desc',
            'per_page'  => 25,
        ];
        if ($cursor) $params['cursor'] = $cursor;

        $url = $baseUrl . '?' . http_build_query($params);
        $response = json_decode(file_get_contents($url), true);

        $allFixtures = array_merge($allFixtures, $response['data']);
        $cursor = $response['pagination']['has_more']
            ? $response['pagination']['next_cursor']
            : null;
    } while ($cursor);

    return $allFixtures;
}

cURL

First page:

curl "https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&order=desc&per_page=25"

Next page (replace CURSOR_VALUE with the value of next_cursor from the previous response):

curl "https://api.sportmonks.com/v3/football/fixtures
?api_token=YOUR_TOKEN&order=desc&per_page=25&cursor=CURSOR_VALUE"

Initial data load

To seed a local database quickly, add filters=populate to your request. This raises the page size limit to 1,000 and strips all includes so responses are as lightweight as possible:

https://api.sportmonks.com/v3/football/fixtures?api_token=YOUR_TOKEN&filters=populate

Note: includes are disabled when filters=populate is set. Use this only for bulk data loads where you want base entity fields only.

Rate limits

Every page request counts as one API call against your rate limit. Fetching 10 pages costs 10 calls. If you need to bulk-load data, use filters=populate with a large per_page to minimise the number of calls required.

Backwards compatibility

The original page and next_page approach continues to work for existing integrations. New integrations should use cursor pagination, which is faster and puts less load on both your client and our infrastructure.

Related

• Best practices

• Rate limiting

• Fixtures endpoint