> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-build-a-live-race-tracker.md). # How to Build a Live Race Tracker > **✅ Included in All Plans** > > The livescores endpoint is included at no additional cost. > > Plans differ only in leagues and API call limits. > > [Compare plans →](https://www.sportmonks.com/football-api/plans-pricing/) This guide shows you how to use the livescores endpoint to build a real-time race tracker that displays current positions, lap counts, and pit stop activity during a live session. ### When to use this Use the livescores endpoint when you want to: * Display a live race feed with current driver positions * Show real-time lap counts and session progress * Track pit stops and stints as they happen during a race ### How to retrieve the data The `GET All Livescores` endpoint returns all currently live and near-live fixtures: ```http GET https://api.sportmonks.com/v3/motorsport/livescores?api_token={your_token} ``` For a race tracker you will need position data, lap progress, and pit stop activity. Use the following includes: ```http GET https://api.sportmonks.com/v3/motorsport/livescores ?api_token={your_token}&include=state;results;latestLaps;latestPitstops;participants ``` The maximum include depth on this endpoint is `3`. **Available includes for live race tracking:** | Include | What it returns | | ---------------- | -------------------------------------------------------------- | | `state` | Current fixture state (e.g. in progress, finished) | | `results` | Current driver positions and classification | | `latestLaps` | The most recent lap data for all drivers | | `latestPitstops` | The most recent pit stop entries | | `participants` | Driver and team details for the session | | `metadata` | Session-level data: current lap count, total laps, fastest lap | To add session metadata (lap counter, race distance, fastest lap): ```http GET https://api.sportmonks.com/v3/motorsport/livescores ?api_token={your_token}&include=state;results;metadata;latestLaps;latestPitstops ``` The type references for `results` and `metadata` fields are documented in: * [Results and Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference) * [Metadata and Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference) ### Working with the data Poll the endpoint on a fixed interval to keep your UI current. A 10-15 second interval is a reasonable default - more frequent polling increases API call usage against your plan's hourly limit. ```javascript const API_TOKEN = 'your_token'; async function fetchLiveRace() { const response = await fetch( `https://api.sportmonks.com/v3/motorsport/livescores?api_token=${API_TOKEN}&include=state;results;metadata;latestLaps` ); const { data } = await response.json(); // Filter to race sessions only (name === 'Race') const races = data.filter(fixture => fixture.name === 'Race'); return races; } // Poll every 15 seconds setInterval(fetchLiveRace, 15000); ``` Each fixture in the response includes the `name` field (`"Practice 1"`, `"Qualifying"`, `"Race"`, etc.) and a `length` field that returns the total number of laps for race sessions. The `leg` field indicates which session within a session type this is. For example, `"2/3"` means Practice 2 of 3. Note that `leg` returns `"1/1"` for Practice 1 when the other practice sessions are replaced by sprint sessions. ### Common pitfalls **The endpoint returns all live and near-live sessions, not just races.** Filter by the `name` field if your tracker is race-only. **`latestLaps` and `latestPitstops` return only the most recent entries**, not the full race history. To retrieve full lap history for a fixture, use the `GET Laps by Fixture ID` endpoint after the session ends. **`length` means different things depending on session type.** For practice and qualification sessions, `length` is the planned session duration in minutes. For race sessions, `length` is the total lap count. ### Advanced usage To show a live gap-to-leader column, extract the `position` value from the `results` include for each driver, sort by position, and calculate the time delta between position 1 and each subsequent driver. The results type reference documents the specific `type_id` values for position, gap, and interval data. ### Common errors | Status | Likely cause | | ------ | ---------------------------------------------- | | `401` | Missing or invalid `api_token` | | `429` | Rate limit exceeded - reduce polling frequency | ### See also **Live endpoints** * [GET All Livescores](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live/get-all-livescores.md) **Type references** * [Results and Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference) * [Metadata and Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference) **Related entities** * [Live](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/live.md) * [Fixture](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture.md) * [Lap](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/lap.md) * [Pitstop](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/pitstop.md) ### FAQ **How often should I poll the livescores endpoint?** There is no minimum interval enforced by the API, but your plan has an hourly call limit. For a typical race tracker with a handful of includes, polling every 10-15 seconds is a practical balance between freshness and call usage. **What does `state_id` mean in a live fixture?** The `state` include returns the fixture's current state object. Use the `GET All States` endpoint (`/v3/motorsport/states`) to retrieve the full list of states and their IDs. **Can I retrieve live data for a specific fixture rather than all live sessions?** The livescores endpoint returns all live sessions. To scope down to a single fixture, filter client-side by `id` after fetching, or use the `GET Fixture by ID` endpoint with the same includes once you know the fixture ID. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-build-a-live-race-tracker.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.