> For the complete documentation index, see [llms.txt](https://docs.sportmonks.com/v3/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sportmonks.com/v3/api-faq.md). # API FAQ Answers to common questions about the Sportmonks Football API v3, including access, coverage, odds, integration and troubleshooting. ### Getting started and migration #### How do I get an API token? Create an account and manage your API token in [MySportmonks](https://my.sportmonks.com/). Keep the token on your server. See [Authentication](https://docs.sportmonks.com/v3/welcome/authentication) for supported authentication methods. #### My API token is not working. What should I check? Check that the token is copied correctly, included in your request and associated with an active subscription that covers the requested data. Inspect the HTTP status and response message before changing your integration. #### Should I separate development and production? Keep development traffic separate where practical, and monitor the quota used by both environments. Do not assume that creating another token gives you a separate subscription allowance. #### Why was API 3.0 introduced, and why should I migrate? API 3.0 introduces a data model designed to support more sports and continued product development. Existing API 2 integrations should follow the [API 2 and API 3 comparison](https://docs.sportmonks.com/v3/welcome/differences-between-api-2-and-api-3) when planning migration. #### How long will API 2.0 remain available? API 2.0 is listed as deprecated in this documentation. Contact for the retirement schedule applicable to your integration. #### How does historical data compare with API 2.0? Historical data was transferred to API 3.0, although some statistical gaps may remain. If a historical value differs, check the competition, season, fixture and statistic type, then send the relevant IDs and a redacted request to support. #### Where did localTeam and visitorTeam go? Request the `participants` include. Use each participant's `meta.location` value to identify home and away teams; do not depend on array order. ### Data and coverage #### Why is my data missing? Check your subscription, requested includes, filters, competition coverage and fixture state. A missing relationship may simply not have been requested. Data such as lineups may not yet be available, and a finished fixture does not guarantee every data type is covered. See [Includes](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/includes) and [States](https://docs.sportmonks.com/v3/definitions/states). #### Which leagues and data features are included? Use the [Coverage Finder guide](https://docs.sportmonks.com/v3/tutorials-and-guides/guides/how-to-use-the-coverage-finder) to explore coverage, and check your active subscription in [MySportmonks](https://my.sportmonks.com/). League access and availability of a particular feature are separate checks. [GET All Leagues](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/leagues/get-all-leagues) lists leagues available within your subscription. The endpoint is `https://api.sportmonks.com/v3/football/leagues`. Follow pagination before treating the result as a complete list. ``` // Server-side JavaScript. Read the token from your environment. const url = new URL('https://api.sportmonks.com/v3/football/leagues'); url.searchParams.set('api_token', process.env.SPORTMONKS_API_TOKEN); const response = await fetch(url); if (!response.ok) throw new Error('Request failed: ' + response.status); const payload = await response.json(); console.log(payload.data); // This page of accessible leagues console.log(payload.pagination); // Check whether more pages exist ``` #### How do I get historical fixtures? Use [GET Fixtures by Date](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-date) or [GET Fixtures by Date Range](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/fixtures/get-fixtures-by-date-range) within your subscription’s leagues. The default history window is the **three most recent seasons per league**, rather than a fixed number of calendar years. The Historical Data add-on unlocks older available seasons and their covered football data. **Historical data is always included in all Special Plans and Enterprise Plans**. Historical depth varies by league and feature; the add-on does not cover odds or extend Premium Odds retention. #### Why can I access fewer players than in API 2.0? API 3 access is based on players who have played for teams covered by your plan. API 2 could include inactive, duplicate or non-existing player records, so raw totals are not a reliable migration comparison. #### What is the difference between Standard and Advanced statistics? Standard and Advanced core-statistics packages describe the previous pricing model. Under the current setup, core statistics are included across paid base plans; plans scale by league capacity and API usage. Separate add-ons such as xG still have their own tiers. Check league-level coverage and your active subscription before relying on a statistic. See the current pricing announcement: #### Which predictions are available? Prediction types include match-result, goals, both-teams-to-score and other probabilities. Use the [Probabilities guide](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/odds-and-predictions/predictions/probabilities) for the maintained reference and check your subscription and fixture coverage. #### How often is data updated? Frequency depends on the data type, competition, fixture phase and feed. Live data can change throughout a match, and post-match statistics can be corrected afterwards. Reference data generally needs less frequent refreshing. Check the relevant feature or feed documentation rather than applying one timing promise to all data. **Update frequency by data type** The timings below describe typical update behaviour. They are not guaranteed end-to-end latency or a requirement to poll every endpoint at the same interval. Availability depends on league and feature coverage. | Data type | Typical update frequency | When it updates | | ---------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Live scores | 10–30 seconds | During live matches | | Match events | 30–60 seconds | Goals, cards and substitutions during the match | | Statistics | 30–60 seconds | During and after matches | | Lineups | 4–6 times per day for higher-coverage leagues; every 5 minutes in the final hour before kickoff | Checked before kickoff as lineup information becomes available | | Standings | After each match | Shortly after match completion | | Fixtures | Daily | New fixtures and date changes | | Teams | Weekly | Squad and manager updates | | Players | Weekly | Transfers and injuries | | Leagues | Monthly | Seasonal updates | | Venues | When stadium information changes | Reference-data changes | | Types and states | Static reference data | Refresh when definitions are added or changed | **Before the match** * Lineups: updated 4–6 times per day for higher-coverage leagues and checked every 5 minutes during the final hour before kickoff. * Weather conditions: updated 4 times per day and every 30 minutes for upcoming fixtures. * Pre-match odds: Standard prices typically refresh every 1–10 minutes and Premium prices around every minute. Timing varies by bookmaker and event; see “How quickly do odds update?” below. **During the match** * Scores: typically updated within 10 seconds of a goal. * Events and statistics: updated every 30–60 seconds. * In-play odds: updated every 2–10 seconds. * Live commentary: updated at the same frequency as events. * Player ratings: available live and updated every minute. **After the match** * Final statistics: available within 10 minutes, with corrections possible over the following days. * Player ratings: updated alongside post-match statistics where applicable. * Standings: available shortly after match completion. * Match highlights: not currently available. **Choosing a polling interval** Polling frequency is separate from the provider update frequency and delivery latency. Poll only the data you need, cache reference data, respect your request allowance, and allow for post-match corrections. The latest-updated livescores endpoint has its own 10-second lookback; changes to events or statistics includes alone do not trigger inclusion. ### Odds #### How do Standard and Premium Odds differ? Premium Odds is supplied in partnership with TXOdds and includes opening prices and subsequent price changes. Compare the feed's coverage, speed and history against your requirements. #### Which bookmakers and markets are included? Check the shared feed comparison: [Bookmakers](https://docs.google.com/spreadsheets/d/1eXh5jmfgaRXd7f2JYXP770AD4AsePoyxG67vVy-fz48/edit?gid=556089710#gid=556089710) and [Markets](https://docs.google.com/spreadsheets/d/1eXh5jmfgaRXd7f2JYXP770AD4AsePoyxG67vVy-fz48/edit?gid=0#gid=0). It distinguishes Standard, Premium and Premium Lite. #### How quickly do odds update? Standard pre-match prices typically refresh every 1–10 minutes; Premium pre-match prices around every minute. In-play updates typically take 2–10 seconds. Refresh frequency is separate from the delay between a bookmaker changing a price and that change reaching the API. The previous odds FAQ described delivery delays of up to 20 minutes for Standard pre-match, 20 seconds for Standard in-play and two minutes for Premium pre-match. These are indicative feed expectations, not guaranteed maximums or an SLA; actual delay varies by bookmaker, event and feed. Confirm time-sensitive requirements with support. #### When do odds become available? Standard Bet365 and Premium prices can appear about three weeks ahead; other Standard bookmakers typically about two weeks ahead. Timing varies by bookmaker and event. #### How does Premium Odds history work? Opening prices and subsequent changes remain accessible until seven days after the fixture's `starting_at` time. #### What are winning odds? The `winning` flag identifies a winning selection. It is supported for Standard pre-match odds. A default `false` value alone does not establish that a selection has been settled as a loss. #### How do I poll Standard and Premium Odds for recent updates? For Standard pre-match odds, use `/odds/pre-match/latest`. It returns updates from the previous 10 seconds; polling every five seconds creates overlap to allow for request time. For Premium, use [Updated Premium Odds Between Time Range](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/premium-odds-feed/premium-pre-match-odds/get-updated-premium-odds-between-time-range), with overlapping timestamp ranges. Deduplicate repeated results and stay within your request allowance. #### Do you store opening and closing odds? Standard Odds provides the most recent collected value. Its first and last observed prices are not guaranteed to be the bookmaker's official opening and closing prices. Store observations yourself if you need a price timeline; Premium Odds provides historical price tracking. #### Which markets support winning calculations? Check the market's winning-calculation flag. Winning calculations are listed for market IDs 1, 10, 14, 18, 19, 33, 38, 39, 41, 44, 50 and 51. Verify the current market response before relying on a calculation. ### Integration and development #### How do I integrate livescores? Use server-side polling, cache the results and share them with your clients. Set the interval according to the data you need and your request allowance. Avoid starting a separate upstream polling loop for every visitor. [GET Latest Updated Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores/get-latest-updated-livescores) has a fixed 10-second lookback for specified core fixture fields. Changes to includes such as events or statistics alone do not trigger inclusion. Refresh those data explicitly where needed, and resynchronise after a polling interruption. #### How do deleted and postponed fixtures work? Deleted fixtures represent incorrect records and stop receiving updates. A postponed fixture keeps its fixture ID while its start date or time is updated. Synchronise status and schedule changes instead of creating a new fixture solely because kickoff changed. #### How do placeholders work? Placeholder participants represent teams that are not yet known, such as a group winner in a knockout bracket. Once determined, the real participant replaces the placeholder. Refresh the fixture's participants rather than storing a placeholder as the permanent team. See [Placeholders](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/placeholders). #### How does pagination work? Read the response's pagination metadata and continue while more results are available. Do not assume the first page contains everything or rely on a total page count. Respect the page-size limit of the endpoint. See [Pagination](https://docs.sportmonks.com/v3/tutorials-and-guides/tutorials/introduction/pagination). #### What is the difference between includes and selects? `include` adds related data; `select` limits fields on the base entity. Request only what the application needs and check the endpoint's supported relationships and fields. #### Can I use React, Vue or Angular? Yes. Have your frontend call your own backend, and let the backend authenticate with Sportmonks. Handle loading, errors and stale data in the frontend while keeping your API token out of browser code. #### Can I use the API in production? Build in timeouts, bounded retries, caching, usage monitoring and graceful handling of missing data. Store credentials securely and serve clients through your backend. Technical production readiness does not determine commercial licensing rights. **Production readiness checklist** * Store tokens in server-side environment variables or a secret manager; keep them out of frontend bundles and logs. * Serve browser and mobile clients through your backend over HTTPS. * Handle non-success HTTP statuses, invalid responses, missing relations and null values explicitly. * Set request timeouts and bounded retries with backoff for transient failures. Avoid retrying invalid credentials or unsupported requests. * Track entity-specific request allowances and respect the indicated reset on a 429 response. * Cache reference data and share upstream polling across users. Choose separate refresh intervals for live and reference data. * Follow pagination, deduplicate overlapping updates, and resynchronise after missed polling windows. * Monitor latency, error rates, quota usage and data freshness; configure actionable alerts and error tracking. * Provide loading, empty, stale-data and unavailable states. Do not silently convert missing values to zero. * Test expected peak traffic and failure scenarios, including timeouts and rate limits. * Back up application-owned data and document recovery procedures and operational ownership. * Verify subscription coverage, required add-ons and applicable commercial usage rights before launch. See [Best practices](https://docs.sportmonks.com/v3/welcome/best-practices). ### Rate limits and performance #### What is the difference between endpoints and entities? An endpoint is a URL you request; an entity is the resource bucket used for rate limiting. Several endpoints can share one bucket. Check `rate_limit.requested_entity` in the response instead of assuming each URL has its own allowance. #### How does the rate limiter work? Limits apply per entity per hour, starting with the first request in that window. Allowances depend on your plan and add-ons. Hitting one entity's limit does not automatically exhaust another's. See the [Rate limit reference](https://docs.sportmonks.com/v3/api/rate-limit) for current allowances. #### How do I track usage? Check MySportmonks and the response's `rate_limit` object, including `remaining`, `requested_entity` and `resets_in_seconds`. The usage endpoint is `GET https://api.sportmonks.com/v3/my/usage`. #### Why am I getting rate limited? A `429` response means the relevant allowance is exhausted. Wait for the indicated reset, then retry within a bounded policy. Count all traffic using the subscription. For example, one polling loop running every five seconds makes 720 requests per hour. Allow for other requests made during that same window. #### How can I reduce API calls and response size? Combine related data with supported includes, cache reusable data, request only needed fields, and use multi-ID endpoints within their documented limits. Reduce polling outside relevant match periods. Measure savings for your own workload rather than assuming a universal percentage. #### What should I cache, and for how long? Use these as starting TTLs for your own cache, not provider update guarantees. Shorten them when your product needs fresher data, refresh unknown IDs, and invalidate affected entries after subscription or league changes. | Reference data | Suggested starting TTL | | ---------------------- | ---------------------------------------------------- | | Types and states | 1 day; up to 1 week if unknown IDs trigger a refresh | | Leagues | 1 day | | Team profile fields | 1 hour | | Venues | 1 week | | Markets and bookmakers | 1 day | Do not apply reference-data TTLs to live scores, odds, current injuries or included statistics. Cache keys must distinguish the account, endpoint, parameters, locale and requested relationships. Never share one account’s cached response with another account. **Worked example: cache the complete Types catalogue** ``` // Server-side JavaScript (Node.js 20+). const token = process.env.SPORTMONKS_API_TOKEN; if (!token) throw new Error('Missing SPORTMONKS_API_TOKEN'); const referenceCache = new Map(); async function getAllTypes({ refresh = false } = {}) { const cached = referenceCache.get('types'); if (!refresh && cached && cached.expiresAt > Date.now()) return cached.rows; const rows = []; let cursor; do { const url = new URL('https://api.sportmonks.com/v3/core/types'); url.searchParams.set('api_token', token); url.searchParams.set('per_page', '50'); if (cursor) url.searchParams.set('cursor', cursor); const response = await fetch(url, { signal: AbortSignal.timeout(10000) }); if (!response.ok) throw new Error('Types request failed: ' + response.status); const payload = await response.json(); if (!Array.isArray(payload.data)) throw new Error('Invalid Types response'); rows.push(...payload.data); if (!payload.pagination?.has_more) break; const next = payload.pagination.next_cursor; if (!next || next === cursor) throw new Error('Missing or repeated cursor'); cursor = next; } while (true); referenceCache.set('types', { rows, expiresAt: Date.now() + 86400000 }); return rows; } let types = await getAllTypes(); // Reuse this cached list for ID lookups. If a returned ID is unknown: // types = await getAllTypes({ refresh: true }); ``` This example caches only a successful, fully paginated response. It keeps the token on the server and out of error messages. The in-memory cache lasts only for this process; use a shared cache and coalesce concurrent refreshes in a multi-instance application. Add bounded retries for transient failures and respect the rate-limit reset before retrying a 429. ### Billing and plans #### What is the difference between plans? Compare league allowances, data access, add-ons, request limits and billing terms on the [Football API pricing page](https://www.sportmonks.com/football-api/#plans-pricing). Check MySportmonks for the entitlements attached to your subscription. #### Is there a Free plan or a trial? The [current plan reference](https://docs.sportmonks.com/v3/api/rate-limit) lists a Free plan for the Danish Superliga and Scottish Premiership, with no expiry or credit card requirement, and a 14-day paid-plan trial with no credit card required upfront. Check the signup flow for the applicable terms. #### Can I cancel, and is annual billing available? Manage your subscription in MySportmonks. Check the current cancellation, renewal and annual billing terms before changing your plan. Contact if you need help choosing a billing option. ### Troubleshooting #### How do I debug an API response? Check the HTTP status, parse the JSON body, and inspect the response message, data and rate-limit metadata. Confirm your endpoint, IDs, filters and includes in the [API Playground](https://my.sportmonks.com/api/playground). Redact tokens before sharing logs or requests. See [Error codes](https://docs.sportmonks.com/v3/api/error-codes). 1. Reproduce one failing request on your server or in the API Playground. Record the endpoint, HTTP status and affected entity IDs; redact the token. 2. Inspect the response body before assuming that an empty data array is an error. 3. Check authentication, subscription and league/feature coverage. 4. Remove optional includes, filters and select fields, then add them back individually using the endpoint reference. 5. Inspect pagination, fixture state, date/time zone and rate\_limit metadata. A missing include or another page can explain apparently missing data. 6. Compare a known covered fixture. If the problem persists, send support the redacted request, response, UTC timestamp and IDs. #### Why am I getting CORS errors? Inspect the browser's Network panel to identify which request and server rejected the origin. Route Sportmonks calls through your backend to protect your API token, and configure your own backend's allowed origins as needed. A CORS error alone does not prove the token is invalid. #### How do I handle null values? Check that the include was requested and that the data is available. Handle absent values explicitly. For an included participants array: ``` const homeName = fixture?.participants ?.find(participant => participant.meta?.location === 'home') ?.name ?? 'Unknown'; ``` #### How do I search for teams and players? Use the team and player search endpoints under `https://api.sportmonks.com/v3/football`: `/teams/search/{name}` and `/players/search/{name}`. URL-encode the search term and check pagination and subscription access. ### Still have questions? Contact with the affected endpoint, fixture or league IDs, HTTP status and a redacted example. Never include your API token.
#### Does the Football API support webhooks? No. The Sportmonks Football API does not support webhooks. To receive updates, poll the API from your server, cache the responses and share them with your application. Choose your polling interval according to the data you need and your request allowance. See [How often is data updated?](https://docs.sportmonks.com/v3/api-faq#how-often-is-data-updated) for the difference between polling frequency, data update frequency and delivery latency. For live fixtures, see [GET Latest Updated Livescores](https://docs.sportmonks.com/v3/endpoints-and-entities/endpoints/livescores/get-latest-updated-livescores) and its documented lookback and update conditions. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.sportmonks.com/v3/api-faq.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.