# Schedules > **🏎️ Motorsport API Required** > > All Schedules endpoints require an active Motorsport API subscription (€79/mo, 3,000 API calls/hr). > > [View pricing →](https://www.sportmonks.com/formula-one-api/) 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**](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/schedules/get-schedule-by-season): returns the complete schedule for a provided season ID, including all stages, fixtures, and venues. #### **Include options** {% hint style="info" %} No includes are available for the Schedules endpoint. Stages, fixtures, and venue data (including track metadata) are all embedded directly in the response. {% endhint %} #### **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](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-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](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-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: ```http GET /v3/motorsport/schedules/seasons/SEASON_ID?api_token=YOUR_TOKEN&page=2 ``` #### **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 `placeholder` becomes `false` (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](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live) instead. #### **Common requests** **Full season schedule:** ```http GET /v3/motorsport/schedules/seasons/SEASON_ID?api_token=YOUR_TOKEN ``` **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: | | Schedules endpoint | Manual assembly | | ------------------ | ----------------------------------- | --------------------------------------- | | 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](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) and [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/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: * [Stage](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/stage) * [Fixture](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/fixture) * [Venue](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/entities/venue) #### **Related pages** * [Stages](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/stages) - Individual race weekend queries with full include options * [Fixtures](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/fixtures) - Individual session queries with full include options * [Venues](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/venues) - Circuit queries with full include options * [Live](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/live) - Real-time session data for active fixtures * [Seasons](https://docs.sportmonks.com/v3/motorsport-api/endpoints-and-entities/endpoints/seasons) - Look up season IDs * [Metadata & Per-Season Data Type Reference](https://docs.sportmonks.com/v3/motorsport-api/welcome/metadata-and-per-season-data-type-reference) --- # 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/endpoints-and-entities/endpoints/schedules.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.