▶️Getting Started

🏎️ Motorsport API required
This API requires an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
View pricing →

This guide walks you through everything you need to make your first Motorsport API request - from obtaining your API token to retrieving live session data. By the end, you will have a working request and a clear picture of how the API is structured.

Before you start

You will need:

A Sportmonks account with an active Motorsport API subscription
Your API token from MySportmonks
Basic familiarity with REST APIs and JSON responses

If you are migrating from the old Formula One API v1, read the Migration Guide first - endpoint paths, IDs, and terminology have all changed.

Step 1: Get your API token

Log in to MySportmonks, navigate to API, and copy your token. Keep it private - do not expose it in frontend code or commit it to version control.

There is no token expiry. Your token remains valid until you manually revoke it.

Step 2: Make your first request

The base URL for all Motorsport API v3 endpoints is:

https://api.sportmonks.com/v3/motorsport

There are two ways to pass your token. Both are equally valid and count towards the same rate limit.

Query parameter:

https://api.sportmonks.com/v3/motorsport/leagues?api_token=YOUR_TOKEN

Authorization header:

Authorization: YOUR_TOKEN

Try the leagues endpoint now - it requires no parameters and gives you a clean first response:

curl "https://api.sportmonks.com/v3/motorsport/leagues?api_token=YOUR_TOKEN"

A successful response looks like this:

{
  "data": [
    {
      "id": 3468,
      "sport_id": 2,
      "country_id": 190324,
      "name": "Formula 1",
      "active": true,
      "short_code": "F1",
      "image_path": "https:\/\/cdn.sportmonks.com\/images\/motorsport\/leagues\/12\/3468.png",
      "type": "league",
      "sub_type": "international",
      "last_played_at": "2026-03-14 07:00:00",
      "category": 1,
      "has_jerseys": false
    },
    {
      "id": 3536,
      "sport_id": 2,
      "country_id": 190324,
      "name": "Formula 1 Pre-Season Testing",
      "active": true,
      "short_code": "F1 PST",
      "image_path": "https:\/\/cdn.sportmonks.com\/images\/motorsport\/leagues\/16\/3536.png",
      "type": "league",
      "sub_type": "international",
      "last_played_at": "2026-02-20 07:00:00",
      "category": 2,
      "has_jerseys": false
    }
  ],
  "pagination": {
    "count": 2,
    "per_page": 25,
    "current_page": 1,
    "next_page": null,
    "has_more": false
  },
  "rate_limit": {
    "resets_in_seconds": 3600,
    "remaining": 2999,
    "requested_entity": "League"
  },
  "timezone": "UTC"
}

Check the rate_limit object in every response - it shows how many calls remain in the current window and when it resets. You have 3,000 calls per hour.

Step 3: Understand the data model

Before exploring endpoints in depth, it is worth understanding how the API organises its data. The key hierarchy is:

League → Season → Stage (race weekend) → Fixture (session)

The most common source of confusion: in this API, a Fixture is a single session (Practice 1, Qualifying, Race) and a Stage is the full race weekend (e.g. Australian Grand Prix). This is the inverse of how the old v1 API used these terms.

Read the full Data Model guide before building anything non-trivial - it covers fixtures, stages, venues, laps, pitstops, and stints in detail.

Step 4: Enrich responses with includes

Most endpoints return a flat response by default. Use the include parameter to pull in related data in a single request rather than making multiple calls.

For example, to get fixtures for a season with their venue and current state included:

https://api.sportmonks.com/v3/motorsport/seasons/ID/fixtures
?api_token=YOUR_TOKEN&include=venue;state

Multiple includes are separated by semicolons. Nested includes use dot notation:

&include=lineups.driver;lineups.details

You can also narrow which fields are returned using select:

&select=name,starting_at&include=venue:name

See request options for full syntax and query complexity for how includes affect your rate limit usage.

Step 5: Navigate a full season

Here is a practical sequence for retrieving a complete season's data from top to bottom:

1. Get all leagues:

GET /v3/motorsport/leagues

2. Get seasons for a league (use the league ID from step 1):

GET /v3/motorsport/seasons/leagues/LEAGUE_ID

3. Get all stages (race weekends) in a season:

GET /v3/motorsport/stages/seasons/SEASON_ID

4. Get all fixtures (sessions) for a stage:

GET /v3/motorsport/fixtures/stages/STAGE_ID

5. Get full session results:

GET /v3/motorsport/fixtures/FIXTURE_ID?include=lineups.details

Each level gives you the IDs needed to query the next. This top-down traversal is the standard pattern for building season dashboards, race trackers, and historical data tools.

Step 6: Working with live data

For live session data, use the livescores endpoint:

GET /v3/motorsport/livescores?api_token=YOUR_TOKEN

This returns all currently active fixtures. To enrich with driver positions and timing:

GET /v3/motorsport/livescores?api_token=YOUR_TOKEN&include=lineups.details

For lap-by-lap timing during a live session, poll the laps endpoint with latest:

GET /v3/motorsport/laps/fixtures/FIXTURE_ID/latest?api_token=YOUR_TOKEN&include=details

latest returns only the most recent lap per driver, keeping response sizes manageable during a race.

Avoid polling faster than every 10-15 seconds during live sessions. The data feed itself does not update faster than this, and aggressive polling will drain your hourly call limit quickly.

Handling errors

Every response includes an HTTP status code. The most common ones you will encounter:

Code

Meaning

Action

200

Success

Process the response

401

Invalid or missing token

Check your api_token value

403

Resource not in your plan

Verify your subscription covers this endpoint

429

Rate limit exceeded

Wait for the window to reset - check rate_limit.resets_in_seconds

500

Server error

Retry with exponential backoff; contact support if persistent

Full error code descriptions are in the response codes reference.

Important: API Tokens in Production

Never include your API token directly in frontend (browser) code - it will be visible to anyone who inspects the page source. Route all API calls through a backend service instead:

Browser → Your Backend → Sportmonks API

Your backend handles authentication and forwards data to the client. This is a hard requirement for any production application.