🗓️Schedules
🏎️ Motorsport API Required
All Schedules endpoints require an active Motorsport API subscription (€79/mo, 3,000 API calls/hr).
A schedule returns the complete season calendar in a single response - every race weekend (stage), every session (fixture), and the circuit (venue with metadata) for each session, all nested together.
This is the most efficient endpoint for building season calendar views, race weekend preview pages, and full schedule displays. It avoids the need to make separate calls to the Stages, Fixtures, and Venues endpoints to assemble the same data.
Available endpoints
GET Schedule by Season: returns the complete schedule for a provided season ID, including all stages, fixtures, and venues.
Include options
No includes are available for the Schedules endpoint. Stages, fixtures, and venue data (including track metadata) are all embedded directly in the response.
Understanding the response structure
The Schedule response is a nested structure with three levels:
data[] - stages (race weekends), ordered by sort_order
└── fixtures[] - all sessions for the stage (Practice, Qualifying, Race)
└── venue - the circuit for that session, with metadata embedded
└── metadata[] - track data: length, direction, type, etc.All data is embedded - there are no additional includes to request. The venue metadata array is populated automatically and contains track-level details such as length, direction, and circuit type. Resolve metadata type IDs using the Metadata & Per-Season Data Type Reference.
Include depth: The Schedules endpoint supports 0 nested includes. All data is pre-embedded in the response.
Working with the schedule response
Stages are returned in sort_order sequence - round 1 first, final round last. Use sort_order rather than starting_at to order rounds correctly in your UI.
Fixtures within each stage include all sessions: Practice 1, Practice 2, Practice 3, Qualifying 1-3, Sprint sessions (where applicable), and the Race. Filter by name or placeholder to isolate specific session types. Exclude placeholder: true fixtures when displaying confirmed sessions only.
Venues are embedded on each fixture (not on the stage). All fixtures within the same stage share the same venue_id and venue object. If you are building a stage-level view, you can safely take the venue from any fixture within that stage.
Venue metadata is already embedded inside the venue object - you do not need to make a separate call to retrieve track length, direction, or circuit type. The metadata array uses type_id values from the Metadata & Per-Season Data Type Reference.
Pagination
The Schedule endpoint paginates at the stage level. A full 24-round F1 season will return results across multiple pages. Iterate using the standard pagination parameters until all stages are retrieved:
Caching guidance
The schedule response is the largest single payload in the Motorsport API - a full season with 24 stages, ~6 fixtures per stage, and venue metadata per fixture is a significant response. Schedule data changes infrequently - session times and venues are confirmed weeks or months in advance and change rarely.
Cache the schedule response aggressively and refresh it:
At the start of each race weekend (in case of last-minute session time changes)
When a session
placeholderbecomesfalse(confirmed timing released)After any official FIA calendar revision
Do not poll this endpoint in real time. For live session data, use the Live endpoint instead.
Common requests
Full season schedule:
Upcoming sessions only (filter client-side):
Fetch the full schedule and filter fixtures where starting_at_timestamp is greater than the current Unix timestamp and placeholder is false.
Current race weekend sessions:
Fetch the full schedule, identify the stage where is_current: true, and read its fixtures array.
Schedules vs assembling data manually
The Schedules endpoint is purpose-built for season calendar use cases. Here is how it compares to assembling the same data through separate endpoint calls:
API calls needed
1 (paginated)
3+ (stages, fixtures per stage, venues)
Includes available
None - all embedded
Full include options on each endpoint
Venue metadata
Embedded automatically
Requires ?include=metadata on Venues
Best for
Season calendars, schedule displays
Targeted queries on specific sessions
Use the Schedules endpoint when you need the full season picture. Use the Stages and Fixtures endpoints when you need to query a specific race weekend or session with additional includes.
Related entities
Get an overview and explanation of all the fields returned in the API response:
Related pages
Last updated
Was this helpful?