Football API questions.
No hidden capabilities.

Stats API is a versioned JSON REST API for football data with stable Stats API identifiers. Its published contract includes 32 operations across competitions, seasons, teams, fixtures and results, standings, squads, match and player statistics, lineups, injuries, season statistics, groups, referee assignments, odds, and coverage. Accounts, API keys, metered requests, and paid plans are available. Coverage varies by league and match; the documentation distinguishes available operations from the 35-operation roadmap.

No. Stats API at stats-api.com is an independent football data API and is not affiliated with TheStatsAPI at thestatsapi.com or with other services that have a similar name. If you meant a different service, check the web address before creating an account. If you are comparing football APIs, compare the published coverage, rate limits, pricing and OpenAPI contract of each, and test with real requests for the leagues you need.

The 32 published operations include competitions, seasons, teams, fixtures and results, standings, squads, match and player statistics, lineups, injuries, season statistics, groups, referee assignments, odds, and coverage. Availability varies by league and match, including statistics and expected goals. Every match reports which kinds of detail are stored (details_available), and player statistics say who started and who played. Check the coverage page and each response before relying on a field. Season statistics, referee assignments, named standings groups, and odds endpoints are available where locally observed. Predictions, heat maps, and shot maps are not available. Player season statistics remain separated by team after transfers; missing fields are null.

Every match returned by the match list and by match detail carries details_available, with four flags: timeline, lineups, statistics and player_statistics. A flag is true when Stats API currently holds that detail for that exact match, so you can skip requests that would return nothing. False means nothing is stored right now: the match may not have been played, the competition may not be covered, or the detail may not have been collected yet. These flags are not the same as the coverage block inside each detail response, which reports whether the data source covers the competition and season. Odds are not included, because they expire; the odds endpoints report their own availability state.

Each player in the per-player match statistics carries started and played. started is true for the starting eleven, including a starter who was later replaced; it comes from the lineup, so where a team's lineup names its eleven a player outside it did not start, and only a team with no named eleven falls back to the provider's substitute flag. played is true when minutes are above zero or a recorded substitution brought the player on, false only when the match is finished, the player began on the bench with no minutes reported, and substitutions are recorded but none brought that player on, and null when it cannot be told. Treat null as unknown, never as false.

In-play match endpoints are available with scheduled polling and observed ingestion timestamps; they are not a sub-minute streaming feed or a freshness guarantee. Prematch, live, and supported prematch player-market odds have dedicated endpoints. Each response distinguishes available, stale, suspended, empty, not collected, and unavailable observations. Coverage varies; the live feed is not attributed to a named bookmaker, and no complete player-props catalogue or betting outcome is promised. Use the current OpenAPI contract and coverage response to check supported operations and available data.

Stats API ingests football data into a normalized store and serves stable public resources. Historical OpenFootball imports and the enabled provider ingestion are recorded separately. The public coverage response exposes dataset observations; cache age alone does not establish source freshness.

Stats API publishes an OpenAPI 3.1 contract, llms.txt orientation, stable resource IDs, UTC timestamps, explicit availability, and predictable error envelopes. A server-side agent tool can use these artifacts to retrieve facts without guessing routes or fields, while keeping the private API key outside the model context.

An agent can use available fixtures and historical results as grounded inputs to a model you operate, but Stats API does not currently provide a prediction endpoint. Any probability or score estimate must be labeled as a model output, with its inputs, assumptions, evaluation, and uncertainty kept separate from API facts.

Use API tool calls for current structured facts such as fixtures, results, statuses, and stable IDs. Use retrieval for durable explanatory material such as documentation and policies. Mixed questions can use both, provided the final answer preserves provenance and does not let retrieved prose override current structured data.

Authenticated API requests use a bearer API key in the Authorization header. Create and revoke keys in the customer dashboard. Keys must remain in server-side environment configuration and must never be placed in query strings, public browser code, logs, or source control.

Yes. Public competition, season, team, and match IDs belong to the Stats API contract rather than to an upstream provider. Provider identifiers remain internal crosswalk data, allowing the ingestion source to change without forcing customers to rewrite stored public IDs.

Events are returned in the provider's order, and each carries a sequence number: its position in the provider's current event list for that match, starting at 1. Use it to keep that order between events in the same minute, such as two events at 45+2. It is an ordinal, not a permanent identifier. While a match is live, or after the provider corrects its feed, events can be added or removed and the numbering can change, so do not store it as a key.

Customer requests are designed to read versioned Redis responses or normalized MySQL data and never wait on an upstream provider. Cache and source freshness are separate concepts. Exact refresh targets depend on the resource and source; every production capability must expose enough timing information for an application to qualify time-sensitive answers.

Yes. Every request admitted through the per-minute limit counts once toward the billing-period quota, including a Redis cache hit and an application-level error produced after authentication. Authentication failures and requests rejected by the per-minute limiter do not consume the billing-period quota. Limits are shared across an account’s API keys. For the Free starter allowance, the same metering rules apply to its one-time total rather than a renewing billing period.

Integrations should explicitly handle 401 for invalid credentials, 404 for an unknown resource, 422 for invalid parameters, 429 for a rate or quota limit, and 503 for temporary unavailability. Retry only temporary failures, honor Retry-After, and never invent a fallback identifier or field.

For new subscriptions, the monthly tiers are Starter at 19.50 USD, Growth at 49.50 USD, and Scale at 149.50 USD. Existing subscriptions retain their original rate. They enforce different monthly and per-minute request limits while including every currently available endpoint. The exact price, trial, and renewal terms are shown again in Polar before checkout is confirmed.

The configured Starter, Growth, and Scale products each include one seven-day trial managed by Polar. Creating a Stats API account does not start a second trial or a paid subscription. When the free signup offer is available, newly created accounts receive a separate one-time allowance of 200 requests, shared across all keys at 30 requests per minute, with no card, renewal, or expiry. Existing accounts keep their granted allowance and usage; older accounts without a grant are not automatically credited. The paid trial begins only through the selected Polar checkout, whose confirmation screen is authoritative for the product, renewal date, and amount.

Open Plans & billing inside your Stats API dashboard to review your subscription and compare plans. Its clearly labeled secure billing action opens Polar for payment details, invoices, eligible plan changes, and cancellation. Access after cancellation follows the paid period and product terms shown at checkout.

The public refund policy explains cancellation and refund eligibility, including mandatory consumer rights that may apply. Billing decisions depend on the transaction and applicable law. Contact support with the account email and transaction reference, but never send an API key or password.

Stats API uses privacy-conscious first-party and Firebase analytics to understand public and signed-in product journeys. First-party records keep the page path, coarse device class, and limited attribution; signed-in page views are linked to the internal account. Firebase receives sanitized paths, bounded interaction categories, and a one-way pseudonymous account identifier for signed-in users. Analytics excludes names, emails, URL query strings, form contents, API keys, request payloads, raw IP addresses, and full user-agent strings from application analytics records. Global Privacy Control and Do Not Track are honored, known bots are excluded, and browser-derived visitor hashes rotate daily.

Use the support address on the contact page and include the affected public resource ID, request ID, UTC time, and a concise reproduction. Do not send private API keys, passwords, Polar tokens, or other secrets. Data-quality reports are reviewed against retained source and ingestion evidence.