Schedule

Contents

What Sportmonks provides

Sportmonks’ schedule endpoints offer a comprehensive, pre-nested data structure across three levels: stages, rounds, and fixtures. Each stage contains its rounds; each round contains its fixtures, including participant names, scores, result details, venue ID, and match state. This organisation enables you to display an entire season schedule without making repeated requests or merging multiple endpoint outputs.

Each fixture within the schedule response includes:

– Fixture ID, name, and starting datetime
– Home and away participants with team IDs, names, and image paths
– Match state (finished, live, upcoming) via state_id
– Full-time and half-time scores
– Result summary string (e.g. “Hearts won after full-time.”)
– Venue ID, leg, and match length

Each stage and round object contains is_current, finished, starting_at, ending_at, and games_in_current_week flags, equipping you to highlight the active stage or round instantly, without extra filtering.

Endpoints

There are three schedule endpoints, each suited to a different use case:

GET Schedules by Season ID returns the full schedule for a specific season, organised by stage and round. Use this endpoint to create a complete league fixture list or a season overview page.

GET https://api.sportmonks.com/v3/football/schedules/seasons/{season_id}?api_token=YOUR_TOKEN

GET Schedules by Team ID returns all schedules for a selected team across all seasons included in your subscription. Use this endpoint to develop a team history page or multi-season fixture archive.

GET https://api.sportmonks.com/v3/football/schedules/teams/{team_id}?api_token=YOUR_TOKEN

GET Schedules by Season ID and Team ID returns the schedule for a single team within a single season, structured by stage and round. Use this endpoint for a team’s season page, a matchday countdown, or a fixture list widget.

GET https://api.sportmonks.com/v3/football/schedules/seasons/{season_id}/teams/{team_id}?api_token=YOUR_TOKEN

Response structure

Unlike most endpoints in Football API v3, schedule endpoints do not support includes or filters. The response is pre-assembled and delivers stages, rounds, and fixtures together in a single nested format. This design makes it one of the most efficient endpoints for full-season rendering, as no additional requests are needed to compile data.

If you want more fixture details than the schedule response provides (such as lineups, events, or advanced stats), use the fixture ID from the schedule response to request specific data from the fixtures endpoint with your required includes.

What you can build with schedule data

– League fixture lists — a full matchday-by-matchday view of every fixture in a season, with scores and results for completed rounds
– Team season pages — a single team’s complete fixture list for the current or any historical season, with results and upcoming matches
– Matchday countdown widgets — use is_current and games_in_current_week to surface only the active round’s fixtures.
– Fixture calendars — map fixtures by date across a season for a visual calendar or agenda view
– Historical archives — retrieve multiple completed seasons for a team or league using the by-team or by-season endpoints
– Match notification systems — pull the schedule once at season start and use the starting_at timestamps to schedule alerts or reminders.

Availability

Schedule data is included in all Starter, Growth, Pro, and Enterprise plans. The available leagues depend on your plan and the leagues you choose. To get schedule data for seasons older than three years, use the historical data add-on. This has a one-time fee of €29 for Starter subscribers. Enterprise plans include full historical access by default.

You can explore the schedule endpoints in the Sportmonks Postman collection or test them directly using the API tester in MySportmonks.

Try it free — all paid plans include a 14-day free trial, and the forever-free plan gives you immediate access to the Danish Superliga and Scottish Premiership with no credit card required.

What is the difference between the schedule endpoints and the fixtures endpoints?

Fixtures endpoints return single match records with many includes, filters, and pagination. Schedule endpoints return pre-nested stages, rounds, and fixtures in one response. This is faster when you need a complete season or team view without having to assemble data from multiple requests.

Do the schedule endpoints support includes or filters?

No. The schedule endpoints give a fixed, pre-structured response with no include or filter options. To get additional data, such as lineups or match events, use the fixture IDs in the schedule response to query the fixtures endpoint.

Which endpoint should I use to show a single team's fixtures for the current season?

Use GET Schedules by Season ID and Team ID. Pass the current season ID and team ID to get that team's fixtures, organised by stage and round.

How do I identify the current active round in a schedule response?

Each round object has an is_current boolean. Rounds also have a games_in_current_week flag. You can use these to highlight rounds with live or upcoming fixtures.

Can I retrieve historical schedules for previous seasons?

Yes. All three schedule endpoints support historical seasons within your subscription. Seasons older than three years require the historical data add-on, available as a one-time purchase starting at €29.

Written by David Jaja

David Jaja is a technical content manager at Sportmonks, where he makes complex football data easier to understand for developers and businesses. With a background in frontend development and technical writing, he helps bridge the gap between technology and sports data. Through clear, insightful content, he ensures Sportmonks' APIs are accessible and easy to use, empowering developers to build standout football applications