Pagination

Responses to broad requests can return more results than fit in a single page. This tutorial covers how to walk through large result sets using cursor-based pagination.

10 minutes Skill level: Beginner Prerequisites: Make your first request

Why pagination exists

A request like "all drivers" or "all fixtures" can return thousands of records. Returning everything in one response would be slow and difficult to work with. Instead, the API splits results into pages and gives you a cursor to fetch the next one.

The pagination object

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

{
  "data": [ ... ],
  "pagination": {
    "count": 25,
    "per_page": 25,
    "current_page": 1,
    "next_cursor": "WzEsMixbMTk3MTAxMDBdLFtbInNwb3J0cy5maXh0dXJlcy5pZCIsMV1dXQ",
    "has_more": true
  }
}

has_more tells you whether there are additional pages. next_cursor is the value you pass on your next request to retrieve them.

Walking through pages

Make a standard request with no cursor.
Use per_page to control how many results come back per page (range 1-50, default 25).
Take the next_cursor value from the response and pass it as a cursor parameter on your next request.
Repeat until has_more is false.

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

When there are no more pages, the response looks like this:

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

Code example

async function fetchAllFixtures(apiToken) {
  const baseUrl = 'https://api.sportmonks.com/v3/motorsport/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;
}

import requests

def fetch_all_fixtures(api_token):
    base_url = "https://api.sportmonks.com/v3/motorsport/fixtures"
    cursor = None
    all_fixtures = []

    while True:
        params = {
            "api_token": api_token,
            "order": "desc",
            "per_page": 25,
        }

        if cursor:
            params["cursor"] = cursor

        response = requests.get(base_url, params=params)
        response.raise_for_status()

        data = response.json()

        all_fixtures.extend(data.get("data", []))

        pagination = data.get("pagination", {})
        cursor = pagination.get("next_cursor") if pagination.get("has_more") else None

        if not cursor:
            break

    return all_fixtures

<?php
function fetchAllFixtures(string $apiToken): array {
  $baseUrl = 'https://api.sportmonks.com/v3/motorsport/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;
}

Populating a database

If you are populating your own database rather than displaying live results, add filters=populate to raise the pagination limit to a maximum of 1000 per page. Note that includes are disabled when this filter is used, to prevent overloading the API.

https://api.sportmonks.com/v3/motorsport/drivers
?api_token=YOUR_TOKEN&filters=populate&per_page=1000

Common pitfalls

Treating the cursor as reusable. A next_cursor value is only valid for the next request in the sequence. Do not store it and reuse it after fetching other pages.

Forgetting that every page counts against your rate limit. Fetching pages 1 through 10 counts as 10 calls against the relevant entity's hourly limit, not one.

Mixing page-number pagination with cursor pagination. The older page= parameter is still supported for existing integrations, but mixing it with cursor= in the same request produces undefined behaviour. Pick one approach per integration.

FAQ

Is the old page-number pagination still supported? Yes, for existing integrations. New integrations should use cursor-based pagination since it is faster and puts less load on the API.

What is the maximum per_page value? 50 by default, or up to 1000 when using filters=populate (with includes disabled).

Last updated 13 days ago

Was this helpful?