What the default fixtures endpoint returns
A GET request to /v1/matches without specifying competition, team, date, season, or round is treated as an unfiltered query. By design, the API returns matches that fall on the current day plus or minus three days. This keeps the payload small and avoids unintended large data pulls when developers forget to add filters.
The limited window also helps stay within the free Starter plan limits of 5,000 requests per month and 60 requests per minute. If a request exceeds the quota, the API returns HTTP 429, signalling that the caller should reduce request volume or upgrade.
How the API determines the date window
When no explicit date parameters are supplied, the service calculates a window centered on the server’s current UTC date. The start of the window is today minus three days, and the end is today plus three days. This calculation is performed internally and does not depend on the competition or team parameters.
If a competition identifier is supplied but the query still lacks date information, the same default window applies. The API does not attempt to infer a season or round from the competition alone; it only narrows the result set to the defined temporal range.
Where the applied range appears in the response
The response includes a meta object that describes the scope of the data returned. The field meta.scope.window contains two ISO‑8601 dates: the start and end of the window used for the query. This makes it explicit to the client what dates were considered.
If the request includes a competition that has no fixtures within that window, the competition identifier is listed under meta.unavailable with a reason explaining why no data was returned. This lets developers understand that the lack of results is due to the date window, not a missing endpoint.
When to add explicit filters
To retrieve a full season, a specific round, or any custom date range, you must include the appropriate filter parameters in the query string. Adding season=2024 or date_from=2024-08-01&date_to=2025-05-31 overrides the default week window and returns all matching fixtures.
Providing a competition identifier together with a season or date range also ensures that the API returns only matches for that competition within the requested period. This approach avoids the need for post‑processing large result sets on the client side.
Implications for season‑long data pulls
If you attempt to pull an entire season without filters, you will receive only the week‑long window and may mistakenly think the API lacks data. Checking meta.scope.window and meta.unavailable helps diagnose this situation.
For larger pulls, be aware of the request limits of your plan. A request that returns many fixtures may still be within the per‑minute limit, but repeated large queries can exhaust the monthly quota, leading to HTTP 429 responses. In such cases, consider paging through the season with smaller date windows or upgrading to a higher plan.
Frequently asked questions
What does meta.scope.window indicate?
It shows the start and end dates the API used for the query. When no date filter is supplied, this will be today minus three days to today plus three days.
How can I retrieve all matches for a season?
Include a season parameter (e.g., season=2024) or specify a date range with date_from and date_to. This replaces the default week window.
What if a competition appears in meta.unavailable?
The identifier is listed because the query found no matches for that competition within the applied date window. Adding an appropriate date filter can make data available.
Will I be charged for large queries?
OpenFoot API does not have overage billing. Exceeding the quota results in HTTP 429, and you can view plan limits on the /pricing page.
Sources and further reading
Product descriptions and examples were checked against the OpenFootAPI v1 contract on 1 November 2026.