# Getting Started > **🏎️ Motorsport API required** > > This API requires an active Motorsport API subscription (€79/mo, 3,000 API calls/hr). > > [View pricing →](https://www.sportmonks.com/formula-one-api/) 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](https://my.sportmonks.com/) * Basic familiarity with REST APIs and JSON responses If you are migrating from the old Formula One API v1, read the [Migration Guide](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/migrating-from-formula-one-api-v1-to-motorsport-api-v3) first - endpoint paths, IDs, and terminology have all changed. ### Step 1: Get your API token Log in to [MySportmonks](https://my.sportmonks.com/), 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: ```http 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:** ```http https://api.sportmonks.com/v3/motorsport/leagues?api_token=YOUR_TOKEN ``` **Authorization header:** ```http Authorization: YOUR_TOKEN ``` Try the leagues endpoint now - it requires no parameters and gives you a clean first response: ```bash curl "https://api.sportmonks.com/v3/motorsport/leagues?api_token=YOUR_TOKEN" ``` A successful response looks like this: ```json { "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](https://docs.sportmonks.com/v3/motorsport-api/welcome/data-model) 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: ```http 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: ```http &include=lineups.driver;lineups.details ``` You can also narrow which fields are returned using `select`: ```http &select=name,starting_at&include=venue:name ``` See [request options](https://docs.sportmonks.com/v3/motorsport-api/welcome/request-options) for full syntax and [query complexity](https://docs.sportmonks.com/v3/motorsport-api/welcome/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:** ```http GET /v3/motorsport/leagues ``` **2. Get seasons for a league (use the league ID from step 1):** ```http GET /v3/motorsport/seasons/leagues/LEAGUE_ID ``` **3. Get all stages (race weekends) in a season:** ```http GET /v3/motorsport/stages/seasons/SEASON_ID ``` **4. Get all fixtures (sessions) for a stage:** ```http GET /v3/motorsport/fixtures/stages/STAGE_ID ``` **5. Get full session results:** ```http 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: ```http GET /v3/motorsport/livescores?api_token=YOUR_TOKEN ``` This returns all currently active fixtures. To enrich with driver positions and timing: ```http 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`: ```http 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](https://docs.sportmonks.com/v3/motorsport-api/welcome/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. ### What to read next * [Data model](https://docs.sportmonks.com/v3/motorsport-api/welcome/data-model) - Understand the League > Season > Stage > Fixture hierarchy * [Authentication](https://docs.sportmonks.com/v3/motorsport-api/welcome/authentication) - Token management in detail * [Request options](https://docs.sportmonks.com/v3/motorsport-api/welcome/request-options) - Includes, field selection, and filters * [Fixtures endpoints](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) - The core of the API * [Live endpoint](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live) - Real-time session data * [Rate limit](https://docs.sportmonks.com/v3/motorsport-api/api/rate-limit) - How the 3,000 calls/hr limit works --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.sportmonks.com/v3/motorsport-api/welcome/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.