> 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? The packages differ in which statistic types they include. Check the [statistics comparison](https://docs.google.com/spreadsheets/d/1dNZqVPJznDtUAjU8110nU_5Ecukle27IRwDXqXqP_P0/edit?usp=sharing) linked from the original API FAQ and confirm your active subscription before choosing a package. #### 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. ### 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 not an end-to-end latency guarantee. #### 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. 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. ### 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). #### 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. --- # 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.