> 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/tutorials/enrich-your-response/how-to-track-lap-by-lap-timing-for-a-race.md). # How to Track Lap-by-Lap Timing for a Race > **✅ Included in All Plans** > > The laps endpoints are 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 retrieve lap timing data for a race - all laps across the full field, individual driver filtering, sector time breakdowns, and live polling for latest laps. ### When to use this Use the laps endpoints when you want to: * Build a lap chart showing position changes throughout a race * Compare pace between two drivers across the same stint * Display sector times to identify where a driver gains or loses time * Poll for the latest lap during a live race to keep a timing display current ### The four laps endpoints | Endpoint | URL pattern | Use case | | ------------------------------------- | ----------------------------------------- | ---------------------------------------------------------- | | GET Laps by Fixture ID | `/fixtures/{id}/laps` | Full race lap history for all drivers | | GET Laps by Fixture ID and Driver ID | `/fixtures/{id}/laps/drivers/{driver_id}` | All laps for one driver in a race | | GET Latest Laps by Fixture ID | `/fixtures/{id}/laps/latest` | Most recently completed lap for each driver (live polling) | | GET Laps by Fixture ID and Lap Number | `/fixtures/{id}/laps/{lap_number}` | All drivers' data for a specific lap number | All four return the same base fields and support the same includes. None of them paginate - the full result set is returned in a single response. ### Base response fields ```json { "data": [ { "id": 2408, "fixture_id": 19402069, "lap_number": 4, "driver_number": 1, "participant_id": 37920800, "is_latest": false } ] } ``` `participant_id` is the driver's ID (the same value as `player_id` in lineups and standings responses). `driver_number` is the car number worn on the car, not the driver's ID. ### Adding sector times with the `details` Include The base response contains only the lap number and driver reference. To get timing data - total lap duration and sector splits - add the `details` include: ``` GET https://api.sportmonks.com/v3/motorsport/fixtures/19408487/laps ?api_token={your_token}&include=details ``` The `details` array on each lap uses `type_id` values. The relevant IDs from the [Results and Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference) are: | type\_id | Name | Value | | -------- | ---------------- | --------------------------- | | `9718` | Lap Duration | Total lap time in seconds | | `9719` | Lap Sector One | Sector 1 time in seconds | | `9720` | Lap Sector Two | Sector 2 time in seconds | | `9721` | Lap Sector Three | Sector 3 time in seconds | | `9722` | Lap Timestamp | Unix timestamp of lap start | | `9723` | Lap Number | The lap number | ### Working with the data #### Fetch all laps with sector times ```javascript const API_TOKEN = 'your_token'; const FIXTURE_ID = 19408487; const response = await fetch( `https://api.sportmonks.com/v3/motorsport/fixtures/${FIXTURE_ID}/laps ?api_token=${API_TOKEN}&include=details` ); const { data: laps } = await response.json(); // Helper to extract a detail value by type_id function getDetail(details, typeId) { return details.find(d => d.type_id === typeId)?.data ?? null; } const parsed = laps.map(lap => ({ lapNumber: lap.lap_number, driverNumber: lap.driver_number, participantId: lap.participant_id, duration: getDetail(lap.details, 9718), sector1: getDetail(lap.details, 9719), sector2: getDetail(lap.details, 9720), sector3: getDetail(lap.details, 9721) })); ``` #### Fetch laps for a single driver ```javascript const DRIVER_ID = 37920800; // Max Verstappen const response = await fetch( `https://api.sportmonks.com/v3/motorsport/fixtures/${FIXTURE_ID}/laps/drivers/${DRIVER_ID} ?api_token=${API_TOKEN}&include=details` ); const { data: driverLaps } = await response.json(); ``` #### Poll for latest laps during a live race ```javascript async function pollLatestLaps(fixtureId, token) { const response = await fetch( `https://api.sportmonks.com/v3/motorsport/fixtures/${fixtureId}/laps/latest ?api_token=${token}&include=details` ); const { data } = await response.json(); return data; } // Poll every 15 seconds during a live session const interval = setInterval(async () => { const latestLaps = await pollLatestLaps(FIXTURE_ID, API_TOKEN); // Update your UI with the freshest lap for each driver }, 15000); ``` `GET Latest Laps by Fixture ID` returns one lap record per driver - the most recently completed lap. Use this during a live race rather than fetching all laps on every poll, which would grow in size as the race progresses. #### Cross-driver pace comparison for a specific lap ```javascript const LAP_NUMBER = 25; const response = await fetch( `https://api.sportmonks.com/v3/motorsport/fixtures/${FIXTURE_ID}/laps/${LAP_NUMBER} ?api_token=${API_TOKEN}&include=details` ); const { data: lapData } = await response.json(); // All drivers' data for lap 25, sorted fastest to slowest const sorted = lapData .map(lap => ({ driverNumber: lap.driver_number, duration: getDetail(lap.details, 9718)?.value ?? null })) .filter(l => l.duration !== null) .sort((a, b) => a.duration - b.duration); ``` ### Common pitfalls **`participant_id` is the driver ID, not the car number.** `driver_number` is the racing car number (e.g. 1 for Verstappen). To join lap data with driver profiles, use `participant_id`, which matches the `id` field on the Driver entity and `player_id` in lineup responses. **`GET Latest Laps` does not mean lap 1.** "Latest" means the most recently completed lap in the current session, not the first lap of the race. During lap 30, this endpoint returns lap 29 or 30 data depending on how recently the lap was completed. **Lap data is not available during practice or qualifying in the same way.** Laps endpoints cover all session types, but the meaning of `lap_number` differs: in qualifying it represents the out-lap or flying lap sequence, not a race lap count. **Sector times are in seconds as decimals, not in `mm:ss.sss` format.** A `lap-duration` value of `91.452` means 1 minute 31.452 seconds. Convert in your application for display. **`details` can be empty for early-race laps.** Timing data may not be available for the formation lap or the first lap immediately after the race start. Handle `null` gracefully. ### Advanced usage To build a fastest lap tracker that updates during a race, combine `GET Latest Laps by Fixture ID` with `?include=details` and track the minimum `lap-duration` value seen so far across all drivers. Compare each new poll's values against your stored minimum and update the fastest lap record when a new personal best appears. To build a driver consistency chart, fetch all laps for one driver with `?include=details`, extract `lap-duration` for each lap, and plot them as a line chart. Laps with pit stop activity will show as outliers - cross-reference with the pitstops endpoint to mark them. ### Common Errors | Status | Likely cause | | ------ | ---------------------------------------------- | | `401` | Missing or invalid `api_token` | | `404` | The `fixture_id` or `driver_id` does not exist | | `422` | Query complexity exceeded - remove includes | ### See also **Laps endpoints** * [GET Laps by Fixture ID](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/laps/get-laps-by-fixture-id.md) * [GET Laps by Fixture ID and Driver ID](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/laps/get-laps-by-fixture-id-and-driver-id.md) * [GET Latest Laps by Fixture ID](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/laps/get-latest-laps-by-fixture-id.md) * [GET Laps by Fixture ID and Lap Number](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/laps/get-laps-by-fixture-id-and-lap-number.md) **Type references** * [Results and Live Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/results-and-live-data-type-reference) **Related entities** * [Lap](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/lap.md) * [Fixture](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture.md) **Related guides** * [How to Fetch Pit Stop Data for a Race](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-fetch-pit-stop-data-for-a-race.md) * [How to Track Tyre Stints](https://docs.sportmonks.com/v3/motorsport-api/tutorials-and-guides/guides/how-to-track-tyre-stints.md) ### FAQ **Do I need to paginate the laps endpoint?** No. All laps endpoints return the full result set without pagination. **How do I find the fixture ID for a specific race?** Use the `GET Schedule by Season` endpoint (`/v3/motorsport/schedules/seasons/{season_id}`) to retrieve all stages and fixtures for the season. Each fixture has an `id` and a `name` field (e.g. `"Race"`) to identify the session type. **Can I get laps for qualifying or practice sessions?** Yes. The laps endpoints work across all session types. Use the fixture `id` for the specific practice or qualifying session rather than the race fixture. --- # 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/tutorials/enrich-your-response/how-to-track-lap-by-lap-timing-for-a-race.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.