When a new season appears

The moment a new season is flagged actual is the moment your product should switch to it. That moment is not the season's start date, and how far ahead it happens depends on the season's coverage level.

Finding the current season

curl "https://api.statscore.com/v2/seasons?token=YOUR_TOKEN&competition_id=13245&is_actual=yes"

The filter is is_actual, the response field is actual

On the request it is is_actual=yes. In the body the same idea is a field named actual: "yes".

Sending actual=yes is not a documented parameter, so it is ignored rather than rejected - you get every season back and no error to tell you why. This is the single easiest mistake to make on this endpoint.

Never derive the current season by sorting on the year in its name. Seasons overlap calendar years, and two seasons of the same competition can be open at once during a transition.

How early the flag appears, and what exists then

Season Stats Level	Flagged actual	Data available at that point
LEGEND	~4 weeks before the start	season, teams, profiles, fixtures, standings, venues
ELITE	~4 weeks before the start	season, teams, profiles, fixtures, standings, venues
EDGE	~2 weeks before the start	season, teams, profiles, fixtures, standings
STARTER	~1 week before the start	season, teams, profiles, fixtures, standings

Two things follow that matter when you build against this:

Venues only come with LEGEND and ELITE. For EDGE and STARTER, a fixture list can be complete while every venue is empty. Do not treat a missing venue as a data error at those levels.

Squads are not part of the promise. For LEGEND and ELITE they usually appear about two weeks before the start, but their absence does not block the season from being flagged actual. So a season can be actual, with full fixtures, and still have no squads - and that is correct behaviour, not a gap to report.

Practical consequence for a scheduled sync

If you mirror competitions locally, the flag is your trigger, and the lead time tells you how long your window is:

• a LEGEND or ELITE season gives you about four weeks to ingest teams, fixtures and venues before anyone needs them
• a STARTER season gives you about one week, and no venues

Combine this with incremental sync: poll /v2/seasons with timestamp and you see the flag flip without re-pulling the whole competition tree.

Next

• Coverage levels - what LEGEND, ELITE, EDGE and STARTER guarantee
• Display a league table - the navigation from season to standings