# Flashscore Sports Data API — 58 record types, 40 sports (`joaobrito/flashscore-sports-data-api`) Actor The most comprehensive Flashscore data API on Apify. Live scores, fixtures, results, match events, statistics, lineups, H2H, standings, team and player profiles, transfers, injuries, rankings, season calendars, search and news. Production-ready JSON, CSV or Excel. Unofficial. - **URL**: https://apify.com/joaobrito/flashscore-sports-data-api.md - **Developed by:** [João Brito](https://apify.com/joaobrito) (community) - **Categories:** Sports, News, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per event This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## ⚽ Flashscore Sports Data API **58 record types · 40 sports · 18 modes — one actor.** Live scores, fixtures, results, stats, lineups, H2H, standings, team & player profiles, transfers, injuries, odds from 130+ bookmakers, rankings, news — normalized, deduplicated, warehouse-ready from **$0.001/result**. --- ### Why this instead of the 10+ fragmented actors on Apify? Search Apify for "flashscore" and you'll find a dozen actors that each do *one* thing — live football, basketball live, tennis fixtures, team stats, H2H, results… each with its own schema, its own scheduling, its own monitoring. **This actor replaces all of them.** | | This actor | Fragmented alternatives | |---|---|---| | **Sports** | **40** | 1–5 per actor | | **Record types** | **58** | 3–15 per actor | | **Actors to install** | **1** | 8–12 | | **Unified schema** | ✅ | ❌ each is different | | **Odds coverage** | **130+ bookmakers, 48 geos** | 0–20 bookmakers | | **Cost estimate before paying** | ✅ `dryRun` | ❌ | | **Budget cap** | ✅ hard USD cap | ❌ | | **Warehouse-ready** | ✅ `dedupeKey` + `schemaVersion` | ❌ post-processing required | --- ### Try it in 30 seconds Two ways to start cheaply: - **Apify free tier** — small experiments typically cost `$0.02–$0.04`. - **Estimate first, pay later** — add `"dryRun": true` to any input. The actor returns the projected cost in `RUN_SUMMARY.estimatedBillingEvents` with **zero data charges**. **Empty input** → live football matches, safe defaults: ```json {} ```` **Today's fixtures** across any sport: ```json { "mode": "matchesByDate", "sports": ["football"], "dateFrom": "2026-05-22", "dateTo": "2026-05-22", "maxItems": 200 } ``` **Full match details** — events + stats + lineups in one bundled record ($0.008): ```json { "mode": "matchDetails", "targetUrls": ["https://www.flashscore.com/match//"], "include": { "events": true, "statistics": true, "lineups": true } } ``` *** ### What you get | Module | Records | Price | |---|---|---:| | Live + fixtures + dates | `match_basic` | `$0.0010` | | Match details + stats | `match_detail`, `match_events`, `match_statistics`, `match_lineups`, `match_h2h`, `match_commentary`, `match_video_highlights`, `match_momentum` | `$0.0030` | | **Premium bundle** | `match-full` — summary + events + stats + lineups in one record. **33% cheaper** than buying each separately ($0.012 → $0.008) | `$0.0080` | | Standings | `competition_standings`, `standing_row` | `$0.0006` | | Teams | `team_profile`, `team_squad`, `team_matches`, `team_transfers`, `team_standings`, `team_news_feed` | `$0.0025` | | Players | `player_profile`, `player_career_stats`, `player_transfers`, `player_injury_history`, `player_match_record` | `$0.0025` | | Competitions | `competition_profile`, `competition_matches`, `competition_draw`, `competition_archive` | `$0.0025` | | News | `news_article` (full body), `match_news`, `team_news_feed` | `$0.0025` | | Rankings + calendars | `ranking_row` (ATP, WTA, FIFA, OWGR…), `season_calendar` (ATP, WTA, PGA, F1…) | `$0.0025` | | Discovery | `search_result`, `country`, `competition`, `featured_competition` | `$0.0025` | | **Odds** (opt-in) | `match_odds` — 20 mainstream bookmakers (bet365, Betfair, William Hill, Unibet…) in one record per match. Add `"include": {"odds": true}` | `$0.0050` | **40 supported sports:** `football`, `tennis`, `basketball`, `hockey`, `american-football`, `baseball`, `handball`, `rugby`, `cricket`, `golf`, `darts`, `snooker`, `boxing`, `mma`, `motorsport`, `cycling`, `esports`, `volleyball`, `beach-volleyball`, `badminton`, `table-tennis`, `field-hockey`, `water-polo`, `aussie-rules` and 16 more. *** ### Odds: 130+ bookmakers, 48 markets No other Flashscore actor on Apify comes close. The default `primary` preset returns **20 mainstream international bookmakers** in a single record per match. Scale up as needed: | Preset | Geos | Bookmakers | |---|---|---| | `primary` (default) | 1 (GB) | 20 incl. bet365, Betfair, William Hill, Ladbrokes, Unibet | | `balanced` | 14 | ~50 | | `extended` | 20 | ~80 | | `global` | 28 | ~100 | | `max` | 48 | 130+ incl. DraftKings, FanDuel, Betano, Bwin, Winamax, Betsson | Enable with `"include": {"odds": true}`. Each preset costs `$0.005` per match per geo. *** ### Real-world cost examples | Scenario | What gets billed | Cost | |---|---|---:| | Premier League matchday — 10 matches, full bundle | 10 × `match-full` | **$0.08** | | Today's fixtures, all 40 sports | ~500 × `match-basic` | **$0.50** | | Live football, every 5 min, full Saturday (6 runs) | 1,200 × `match-basic` | **~$1.20** | | Champions League round of 16 — full bundle | 16 × `match-full` | **~$0.13** | | Weekly Premier League standings | 20 × `standing-row` | **$0.012** | | 50 matches with odds (default preset, 20 books) | 50 × `match-full` + 50 × `odds-record` | **$0.65** | | Single player deep dive — profile + career + transfers + injuries | ~4 × `entity-profile` | **$0.01** | > Add `"dryRun": true` to any input to get a projected cost estimate at zero charge before committing. *** ### Use it from your app #### Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('joaobrito/flashscore-sports-data-api').call({}); const { items } = await client.dataset(run.defaultDatasetId).listItems(); const live = items.filter(row => row.recordType === 'match_basic'); console.log(`${live.length} live matches`); // { recordType, matchId, homeTeamName, awayTeamName, homeScore, awayScore, status, ... } ``` #### Python ```python from apify_client import ApifyClient import os client = ApifyClient(token=os.environ["APIFY_TOKEN"]) run = client.actor("joaobrito/flashscore-sports-data-api").call(run_input={}) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): if item["recordType"] == "match_basic": print(item["homeTeamName"], "vs", item["awayTeamName"], item["status"]) ``` Get your `APIFY_TOKEN` at [console.apify.com/account/integrations](https://console.apify.com/account/integrations). *** ### What a record looks like Every record carries `recordType`, `source`, `sourceUrl`, `scrapedAt`, `schemaVersion`, and a stable `dedupeKey` — safe to replay, trivial to upsert into Postgres, BigQuery, or Snowflake. ```json { "recordType": "match_basic", "source": "flashscore", "sport": "football", "matchId": "4I23FiTQ", "country": "England", "competitionName": "Premier League", "startTime": "2026-05-22T19:00:00.000Z", "status": "1st Half", "statusCategory": "live", "homeTeamName": "Home FC", "awayTeamName": "Away FC", "homeScore": 1, "awayScore": 0, "scrapedAt": "2026-05-22T19:23:45.000Z", "schemaVersion": "2.0.0", "dedupeKey": "match_basic:football:4I23FiTQ" } ``` `statusCategory` is a cross-sport bucket (`scheduled` · `live` · `paused` · `finished` · `postponed` · `cancelled`) so you filter consistently across all 40 sports with the same field. *** ### All 18 modes | Mode | What it does | |---|---| | `live` | Live + same-day matches by sport | | `matchesByDate` | Fixtures + results in a date range | | `matchDetails` | Per-match deep dive: events, stats, lineups, H2H, commentary, highlights, odds | | `team` | Team profile, squad, recent + upcoming matches, transfers, news | | `player` | Player profile, career stats, transfers, injuries, last matches | | `competition` | Profile, fixtures, results, archive, draw, leaderboard, participants | | `standings` | League / competition standings tables | | `h2h` | Head-to-head data for a match or team pair | | `news` | News articles by locale / category — metadata + full body | | `rankings` | ATP, WTA, FIFA, OWGR, FedExCup rankings | | `seasonCalendars` | ATP, WTA, PGA, F1 season calendars | | `search` | Public discovery search by query (teams / players / competitions) | | `topSearch` | Popular discovery suggestions | | `countries` | Country / category catalog, optionally expands to competitions | | `featuredCompetitions` | Editorial top competitions per sport | | `newsLocales` | Catalog of available Flashscore News locales | | `newsCategories` | Catalog of categories per locale | | `bookmakers` | Public bookmaker name catalog by geo | *** ### Controls | Parameter | Description | |---|---| | `mode` | One of the 18 modes above | | `sports` | Array of sport identifiers (40 supported) | | `targetUrls` | Public Flashscore URLs of matches, teams, players, competitions | | `include.*` | `events`, `statistics`, `lineups`, `h2h`, `commentary`, `highlights`, `momentum`, `odds`, `news` | | `maxItems` | Cap per run — default 50, safety net against runaway runs | | `dryRun` | `true` → project cost, emit zero billable records | | `ACTOR_MAX_TOTAL_CHARGE_USD` | Hard USD cap; run halts gracefully at 95% | *** ### Build a historical archive Use Apify Scheduler to run this actor on a daily or hourly cron. The dataset accumulates across runs and the `dedupeKey` on every record makes upserts trivial — you get a clean, append-only historical table even though the actor only scrapes the present. A daily `matchesByDate` job over a few months gives you a solid fixture-and-result archive for backtesting. *** ### Know before you buy - **Latency**: 1–3 seconds wall-clock per request, polling-based. Not suitable for sub-second live trading or WebSocket push feeds. - **No SLA**: best-effort unofficial extractor. Build retries and a cached fallback into your pipeline. - **Cross-run billing**: re-running the actor against the same matches re-bills per the Apify PPE model — `dedupeKey` is for your upsert idempotency, not for skipping charges. - **Public data only**: no login bypass, no CAPTCHA, no paywall. *** ### Support Open an issue on the Apify Actor page: ``` Run ID: Input used: Affected URL or matchId: Expected vs. actual: RUN_SUMMARY warning category (if any): ``` *** > *Unofficial extractor. Not affiliated with, endorsed by, or sponsored by Flashscore or Livesport.* # Actor input Schema ## `mode` (type: `string`): Choose what type of data to extract. Bookmakers mode is betting-adjacent, must be used only where permitted, and is not an odds feed. ## `sports` (type: `array`): Sports to extract. In search and topSearch modes this is a local post-filter because the upstream search service ignores sport parameters. In countries and featuredCompetitions modes, pass an empty array to collect every supported sport catalog. In bookmakers mode, sports is ignored. Country competition expansion is controlled by Include country competitions. In news mode, prefer newsCategoryKeys returned by newsCategories; sports is only used as the fallback feed when no newsCategoryKeys are provided. ## `dateFrom` (type: `string`): Start date in YYYY-MM-DD. Used in matchesByDate mode. ## `dateTo` (type: `string`): End date in YYYY-MM-DD. Keep ranges small in the MVP. ## `targetUrls` (type: `array`): Match, team, player, ranking, public season calendar, public competition page or full Flashscore News category URLs to extract, depending on mode. Only flashscore.com URLs are accepted. In rankings mode, use URLs such as https://www.flashscore.com/tennis/rankings/atp/, https://www.flashscore.com/football/rankings/fifa/, https://www.flashscore.com/golf/rankings/owgr/ or https://www.flashscore.com/badminton/rankings/bwf-singles-men/. In seasonCalendars mode, use URLs such as https://www.flashscore.com/tennis/calendar/atp/ or https://www.flashscore.com/golf/calendar/pga/. In player mode, use URLs such as https://www.flashscore.com/player/gyokeres-viktor/zaBZ1xIk/. For news mode, use mode newsCategories first to discover supported URLs. ## `matchIds` (type: `array`): Optional Flashscore match IDs if known. ## `searchQueries` (type: `array`): Search terms for mode search. Each query must be at least 2 characters. Use topSearch for popular suggestions without a query. ## `searchLimit` (type: `integer`): Maximum search results requested per query or top-search task. Flashscore currently supports useful limits up to 50. ## `searchTypes` (type: `array`): Optional post-filter for search results. Leave empty to return teams, players and competitions. ## `allNewsProjects` (type: `boolean`): In news article mode, collect broad locale coverage while deduplicating equivalent sources internally. In newsCategories mode, fetch every known public news menu. ## `newsProjectIds` (type: `array`): Advanced selector for exact public Flashscore News project ids. Prefer newsLocales for normal use; use mode newsLocales to discover supported locale/project combinations. ## `newsLocales` (type: `array`): Exact Flashscore news locales to use, such as pt, pt-br, en-uk or es-mx. Use mode newsLocales to list available values. ## `newsCategoryKeys` (type: `array`): Optional news category keys returned by mode newsCategories, such as all:all, SPORT:SW9D1eZo or TAG:C8OAR7gM. In news mode, categories are combined with each selected news locale. ## `includeCountryCompetitions` (type: `boolean`): In countries mode, fetch leagues and tournaments inside each discovered country/category. ## `countryCompetitionConcurrency` (type: `integer`): Maximum concurrent competition requests inside each countries task. ## `competitionArchiveSeasons` (type: `integer`): In competition mode, fetch historical standings/draw feeds for this many previous seasons from the public archive. Keep low because each season can expose multiple stage feeds. ## `competitionOddsGeoIpCode` (type: `string`): Two-letter ISO 3166-1 alpha-2 country code used for competition winner odds. Odds availability is geo-dependent; GB usually exposes public winner odds when available. ## `competitionOddsGeoIpSubdivisionCode` (type: `string`): Optional subdivision code (ISO 3166-2 style) used by Flashscore winner odds requests. ## `oddsGeoIpCode` (type: `string`): Legacy match-odds geo country code (ISO 3166-1 alpha-2). If set, the actor derives coverage targets from oddsProjectIds and this geo instead of using the default multi-geo target list. ## `oddsGeoIpSubdivisionCode` (type: `string`): Legacy match-odds subdivision code (ISO 3166-2 style). Used with oddsGeoIpCode when deriving legacy coverage targets. ## `oddsProjectIds` (type: `array`): Legacy match-odds project fan-out. Leave empty to use oddsCoveragePreset or oddsCoverageTargets. If supplied, each project id is requested with oddsGeoIpCode and oddsGeoIpSubdivisionCode. ## `oddsCoveragePreset` (type: `string`): Match-odds geo fan-out (only matters when include.odds is true; include.odds defaults to false). Primary (the default) makes a single request to projectId=2 / geo=GB and returns 20 mainstream international bookmakers (bet365, Betfair, William Hill, Ladbrokes, Paddy Power, Skybet, Betway, BetVictor, BetMGM, Betfred, Coral, Unibetuk, BetUK, Betano.uk, 10bet, 7Bet, Midnite, Parimatch.uk, SpreadEX, Talksportbet) in one match\_odds record at $0.005. Use Balanced (14 geos), Extended (20 geos adds FI, ZA, NL, NO, BE, DE), Global (28 geos) or Max (48 geos) to fan out across regional bookmakers — each geo adds one match\_odds record per match. Heads-up: Pinnacle is not in Flashscore's commercial bookmaker network (validated 2026-05-20 across 186 request patterns — 62 geo × projectId odds combinations and the full 137-bookmaker catalog dump). Higher presets multiply volume without unlocking new bookmaker brands. Ignored when oddsCoverageTargets or legacy odds controls are supplied. ## `oddsCoverageTargets` (type: `array`): Advanced, compliance-sensitive match-odds coverage control. Each target combines a public project id and geo. When supplied, this overrides oddsCoveragePreset but still does not enable odds output unless include.odds and the odds compliance gate are enabled. The default balanced preset uses projectId 2 across multiple geos for broader bookmaker coverage at similar request cost. ## `maxItemsPerNewsTask` (type: `integer`): Optional per-locale/category cap for news article collection. The global Maximum results cap still applies to the whole run. ## `resolveNewsCategoryMetadata` (type: `boolean`): When using newsCategoryKeys, fetch the public news menu once per task to enrich article topics with localized category names. Leave disabled to keep first-page article collection GraphQL-only. ## `rankingScope` (type: `string`): In rankings mode, choose whether to collect only targetUrls, expand related ranking tabs from those URLs, or collect all known public ranking families and their tabs. allKnown covers confirmed public rankings for football/FIFA, tennis, golf, darts, snooker and badminton. ## `include` (type: `object`): Choose optional implemented sections. Odds are advanced and compliance-sensitive: include.odds is disabled by default and only enables geo-dependent odds when legal/product approval and the environment gate allow it. In player, team and competition modes, news enables participant or competition news articles; in rankings mode, liveRankings enables tennis live ranking projections from ral\_\* feeds. articleContent is also compliance-sensitive, disabled by default, and requires its matching environment gate before full public output is emitted. ## `includeRaw` (type: `boolean`): Backward-compatible alias for include.raw. Raw payloads are disabled by default, only for internal debugging, and are removed from public dataset output. ## `acknowledgeRawHighMemory` (type: `boolean`): Acknowledge that combining include.raw=true with oddsCoveragePreset="extended"/"global"/"max" is high-memory. Intermediate records retain every HTTP response body until they are stripped at dataset push time, and these presets fan out odds requests across 20/28/48 geos respectively. The 2026-05-20 performance audit measured peak RAM near 1 GB on this combination, which can OOM-kill a standard 1-2 GB Actor tier. Leave this off (the default) and the parser will reject the high-RAM combination with a clear error. Set to true to opt in explicitly when you know what you are doing. ## `maxItems` (type: `integer`): Maximum number of dataset items to output across the whole run, not per locale/category. Bookmakers mode defaults to 1000 when omitted because the catalog contains more than 100 geo entries. For news article runs, use Maximum news items per task when each locale/category needs its own cap. ## `maxConcurrency` (type: `integer`): Lower values are more polite and stable. Higher values may increase cost and failures. ## `requestDelayMs` (type: `integer`): Politeness delay between requests/pages. ## `locale` (type: `string`): Language/locale preference for public pages where applicable. ## `timezone` (type: `string`): IANA timezone used for date feed requests, such as UTC, Europe/Lisbon or America/New\_York. Output timestamps remain ISO UTC. ## `dryRun` (type: `boolean`): Estimate tasks and billing events without extracting paid detail data. ## `proxyConfiguration` (type: `object`): Optional Apify proxy configuration. Do not use proxies to bypass access controls or evade restrictions. ## Actor input object example ```json { "mode": "live", "sports": [ "football" ], "targetUrls": [], "matchIds": [], "searchQueries": [], "searchLimit": 20, "searchTypes": [], "allNewsProjects": false, "newsProjectIds": [], "newsLocales": [], "newsCategoryKeys": [], "includeCountryCompetitions": true, "countryCompetitionConcurrency": 2, "competitionArchiveSeasons": 0, "competitionOddsGeoIpCode": "GB", "competitionOddsGeoIpSubdivisionCode": "", "oddsGeoIpCode": "PT", "oddsGeoIpSubdivisionCode": "PT13", "oddsProjectIds": [], "oddsCoveragePreset": "primary", "oddsCoverageTargets": [ { "projectId": 2, "geoIpCode": "PT", "geoIpSubdivisionCode": "PT13" }, { "projectId": 2, "geoIpCode": "BR", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "GB", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "ES", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "FR", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "RO", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "AT", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "PL", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "NG", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "CZ", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "DK", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "SE", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "IT", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "GR", "geoIpSubdivisionCode": "" } ], "resolveNewsCategoryMetadata": false, "rankingScope": "targets", "include": { "commentary": false, "events": false, "highlights": false, "statistics": false, "lineups": false, "h2h": false, "momentum": false, "odds": false, "news": true, "liveRankings": false, "articleContent": true, "raw": false }, "includeRaw": false, "acknowledgeRawHighMemory": false, "maxItems": 50, "maxConcurrency": 2, "requestDelayMs": 1000, "locale": "en", "timezone": "UTC", "dryRun": false } ``` # Actor output Schema ## `results` (type: `string`): Extracted and normalized records stored in the default dataset. Every record is validated before writing and includes recordType, source, sourceUrl, scrapedAt, schemaVersion and dedupeKey. Aggregate entity records are preserved and BI/Excel-friendly row-level records are emitted where available. ## `summary` (type: `string`): Summary stored in the default key-value store under RUN\_SUMMARY, including task counts, record counts, warnings, errors, request status counts and billing estimates/events. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("joaobrito/flashscore-sports-data-api").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("joaobrito/flashscore-sports-data-api").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call joaobrito/flashscore-sports-data-api --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=joaobrito/flashscore-sports-data-api", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Flashscore Sports Data API — 58 record types, 40 sports", "description": "The most comprehensive Flashscore data API on Apify. Live scores, fixtures, results, match events, statistics, lineups, H2H, standings, team and player profiles, transfers, injuries, rankings, season calendars, search and news. Production-ready JSON, CSV or Excel. Unofficial.", "version": "1.0", "x-build-id": "oy0vuT1lAqJvplUNR" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/joaobrito~flashscore-sports-data-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-joaobrito-flashscore-sports-data-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/joaobrito~flashscore-sports-data-api/runs": { "post": { "operationId": "runs-sync-joaobrito-flashscore-sports-data-api", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/joaobrito~flashscore-sports-data-api/run-sync": { "post": { "operationId": "run-sync-joaobrito-flashscore-sports-data-api", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode", "maxItems", "maxConcurrency" ], "properties": { "mode": { "title": "Extraction mode", "enum": [ "live", "matchesByDate", "matchDetails", "countries", "featuredCompetitions", "bookmakers", "search", "topSearch", "newsLocales", "newsCategories", "news", "standings", "rankings", "seasonCalendars", "team", "player", "competition", "h2h" ], "type": "string", "description": "Choose what type of data to extract. Bookmakers mode is betting-adjacent, must be used only where permitted, and is not an odds feed.", "default": "live" }, "sports": { "title": "Sports", "type": "array", "description": "Sports to extract. In search and topSearch modes this is a local post-filter because the upstream search service ignores sport parameters. In countries and featuredCompetitions modes, pass an empty array to collect every supported sport catalog. In bookmakers mode, sports is ignored. Country competition expansion is controlled by Include country competitions. In news mode, prefer newsCategoryKeys returned by newsCategories; sports is only used as the fallback feed when no newsCategoryKeys are provided.", "items": { "type": "string", "enum": [ "football", "tennis", "basketball", "hockey", "american-football", "baseball", "handball", "rugby", "floorball", "bandy", "futsal", "volleyball", "cricket", "darts", "snooker", "boxing", "beach-volleyball", "aussie-rules", "rugby-league", "badminton", "water-polo", "golf", "field-hockey", "table-tennis", "beach-soccer", "mma", "netball", "pesapallo", "motorsport", "motorsport-auto-racing", "motorsport-moto-racing", "cycling", "horse-racing", "esports", "winter-sports", "winter-sports-ski-jumping", "winter-sports-alpine-skiing", "winter-sports-cross-country", "winter-sports-biathlon", "kabaddi" ] }, "default": [ "football" ] }, "dateFrom": { "title": "Date from", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Start date in YYYY-MM-DD. Used in matchesByDate mode." }, "dateTo": { "title": "Date to", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "End date in YYYY-MM-DD. Keep ranges small in the MVP." }, "targetUrls": { "title": "Target URLs", "maxItems": 1000, "type": "array", "description": "Match, team, player, ranking, public season calendar, public competition page or full Flashscore News category URLs to extract, depending on mode. Only flashscore.com URLs are accepted. In rankings mode, use URLs such as https://www.flashscore.com/tennis/rankings/atp/, https://www.flashscore.com/football/rankings/fifa/, https://www.flashscore.com/golf/rankings/owgr/ or https://www.flashscore.com/badminton/rankings/bwf-singles-men/. In seasonCalendars mode, use URLs such as https://www.flashscore.com/tennis/calendar/atp/ or https://www.flashscore.com/golf/calendar/pga/. In player mode, use URLs such as https://www.flashscore.com/player/gyokeres-viktor/zaBZ1xIk/. For news mode, use mode newsCategories first to discover supported URLs.", "items": { "type": "string", "pattern": "^https?://([a-z0-9-]+\\.)*flashscore\\.com(/.*)?$", "maxLength": 500 }, "default": [] }, "matchIds": { "title": "Match IDs", "maxItems": 1000, "type": "array", "description": "Optional Flashscore match IDs if known.", "items": { "type": "string", "pattern": "^[A-Za-z0-9]{6,16}$" }, "default": [] }, "searchQueries": { "title": "Search queries", "maxItems": 200, "type": "array", "description": "Search terms for mode search. Each query must be at least 2 characters. Use topSearch for popular suggestions without a query.", "items": { "type": "string", "minLength": 2, "maxLength": 200 }, "default": [] }, "searchLimit": { "title": "Search limit", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum search results requested per query or top-search task. Flashscore currently supports useful limits up to 50.", "default": 20 }, "searchTypes": { "title": "Search result types", "type": "array", "description": "Optional post-filter for search results. Leave empty to return teams, players and competitions.", "items": { "type": "string", "enum": [ "team", "player", "competition" ] }, "default": [] }, "allNewsProjects": { "title": "All news projects", "type": "boolean", "description": "In news article mode, collect broad locale coverage while deduplicating equivalent sources internally. In newsCategories mode, fetch every known public news menu.", "default": false }, "newsProjectIds": { "title": "News project IDs", "type": "array", "description": "Advanced selector for exact public Flashscore News project ids. Prefer newsLocales for normal use; use mode newsLocales to discover supported locale/project combinations.", "items": { "type": "integer", "minimum": 1 }, "default": [] }, "newsLocales": { "title": "News locales", "type": "array", "description": "Exact Flashscore news locales to use, such as pt, pt-br, en-uk or es-mx. Use mode newsLocales to list available values.", "items": { "type": "string" }, "default": [] }, "newsCategoryKeys": { "title": "News category keys", "type": "array", "description": "Optional news category keys returned by mode newsCategories, such as all:all, SPORT:SW9D1eZo or TAG:C8OAR7gM. In news mode, categories are combined with each selected news locale.", "items": { "type": "string" }, "default": [] }, "includeCountryCompetitions": { "title": "Include country competitions", "type": "boolean", "description": "In countries mode, fetch leagues and tournaments inside each discovered country/category.", "default": true }, "countryCompetitionConcurrency": { "title": "Country competition concurrency", "minimum": 1, "maximum": 3, "type": "integer", "description": "Maximum concurrent competition requests inside each countries task.", "default": 2 }, "competitionArchiveSeasons": { "title": "Competition archive seasons", "minimum": 0, "maximum": 10, "type": "integer", "description": "In competition mode, fetch historical standings/draw feeds for this many previous seasons from the public archive. Keep low because each season can expose multiple stage feeds.", "default": 0 }, "competitionOddsGeoIpCode": { "title": "Competition odds geo IP code", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Two-letter ISO 3166-1 alpha-2 country code used for competition winner odds. Odds availability is geo-dependent; GB usually exposes public winner odds when available.", "default": "GB" }, "competitionOddsGeoIpSubdivisionCode": { "title": "Competition odds subdivision code", "pattern": "^[A-Za-z0-9-]{0,16}$", "type": "string", "description": "Optional subdivision code (ISO 3166-2 style) used by Flashscore winner odds requests.", "default": "" }, "oddsGeoIpCode": { "title": "Match odds geo IP code", "pattern": "^[A-Za-z]{2}$", "type": "string", "description": "Legacy match-odds geo country code (ISO 3166-1 alpha-2). If set, the actor derives coverage targets from oddsProjectIds and this geo instead of using the default multi-geo target list.", "default": "PT" }, "oddsGeoIpSubdivisionCode": { "title": "Match odds subdivision code", "pattern": "^[A-Za-z0-9-]{0,16}$", "type": "string", "description": "Legacy match-odds subdivision code (ISO 3166-2 style). Used with oddsGeoIpCode when deriving legacy coverage targets.", "default": "PT13" }, "oddsProjectIds": { "title": "Match odds project IDs", "type": "array", "description": "Legacy match-odds project fan-out. Leave empty to use oddsCoveragePreset or oddsCoverageTargets. If supplied, each project id is requested with oddsGeoIpCode and oddsGeoIpSubdivisionCode.", "items": { "type": "integer" }, "default": [] }, "oddsCoveragePreset": { "title": "Match odds coverage preset", "enum": [ "primary", "balanced", "extended", "global", "max" ], "type": "string", "description": "Match-odds geo fan-out (only matters when include.odds is true; include.odds defaults to false). Primary (the default) makes a single request to projectId=2 / geo=GB and returns 20 mainstream international bookmakers (bet365, Betfair, William Hill, Ladbrokes, Paddy Power, Skybet, Betway, BetVictor, BetMGM, Betfred, Coral, Unibetuk, BetUK, Betano.uk, 10bet, 7Bet, Midnite, Parimatch.uk, SpreadEX, Talksportbet) in one match_odds record at $0.005. Use Balanced (14 geos), Extended (20 geos adds FI, ZA, NL, NO, BE, DE), Global (28 geos) or Max (48 geos) to fan out across regional bookmakers — each geo adds one match_odds record per match. Heads-up: Pinnacle is not in Flashscore's commercial bookmaker network (validated 2026-05-20 across 186 request patterns — 62 geo × projectId odds combinations and the full 137-bookmaker catalog dump). Higher presets multiply volume without unlocking new bookmaker brands. Ignored when oddsCoverageTargets or legacy odds controls are supplied.", "default": "primary" }, "oddsCoverageTargets": { "title": "Match odds coverage targets", "type": "array", "description": "Advanced, compliance-sensitive match-odds coverage control. Each target combines a public project id and geo. When supplied, this overrides oddsCoveragePreset but still does not enable odds output unless include.odds and the odds compliance gate are enabled. The default balanced preset uses projectId 2 across multiple geos for broader bookmaker coverage at similar request cost.", "items": { "type": "object", "required": [ "projectId", "geoIpCode" ], "properties": { "projectId": { "title": "Project ID", "description": "Public Flashscore project id for this odds coverage target.", "type": "integer", "minimum": 1 }, "geoIpCode": { "title": "Geo IP country code", "description": "Two-letter country code used for this odds coverage target.", "type": "string" }, "geoIpSubdivisionCode": { "title": "Geo IP subdivision code", "description": "Optional subdivision code used for this odds coverage target.", "type": "string", "default": "" } } }, "default": [ { "projectId": 2, "geoIpCode": "PT", "geoIpSubdivisionCode": "PT13" }, { "projectId": 2, "geoIpCode": "BR", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "GB", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "ES", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "FR", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "RO", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "AT", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "PL", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "NG", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "CZ", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "DK", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "SE", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "IT", "geoIpSubdivisionCode": "" }, { "projectId": 2, "geoIpCode": "GR", "geoIpSubdivisionCode": "" } ] }, "maxItemsPerNewsTask": { "title": "Maximum news items per task", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Optional per-locale/category cap for news article collection. The global Maximum results cap still applies to the whole run." }, "resolveNewsCategoryMetadata": { "title": "Resolve news category metadata", "type": "boolean", "description": "When using newsCategoryKeys, fetch the public news menu once per task to enrich article topics with localized category names. Leave disabled to keep first-page article collection GraphQL-only.", "default": false }, "rankingScope": { "title": "Ranking scope", "enum": [ "targets", "relatedTabs", "allKnown" ], "type": "string", "description": "In rankings mode, choose whether to collect only targetUrls, expand related ranking tabs from those URLs, or collect all known public ranking families and their tabs. allKnown covers confirmed public rankings for football/FIFA, tennis, golf, darts, snooker and badminton.", "default": "targets" }, "include": { "title": "Detail modules", "type": "object", "description": "Choose optional implemented sections. Odds are advanced and compliance-sensitive: include.odds is disabled by default and only enables geo-dependent odds when legal/product approval and the environment gate allow it. In player, team and competition modes, news enables participant or competition news articles; in rankings mode, liveRankings enables tennis live ranking projections from ral_* feeds. articleContent is also compliance-sensitive, disabled by default, and requires its matching environment gate before full public output is emitted.", "properties": { "commentary": { "title": "Commentary", "type": "boolean", "description": "Include public text commentary when the match exposes it.", "default": false }, "events": { "title": "Events", "type": "boolean", "description": "Include match event rows when available.", "default": false }, "highlights": { "title": "Highlights metadata", "type": "boolean", "description": "Include public highlight metadata when available and permitted.", "default": false }, "statistics": { "title": "Statistics", "type": "boolean", "description": "Include match statistics when available.", "default": false }, "lineups": { "title": "Lineups", "type": "boolean", "description": "Include lineups when available.", "default": false }, "h2h": { "title": "Head-to-head", "type": "boolean", "description": "Include head-to-head match rows when available.", "default": false }, "momentum": { "title": "Momentum", "type": "boolean", "description": "Include match momentum data when available.", "default": false }, "odds": { "title": "Odds", "type": "boolean", "description": "Public match and competition odds across the bookmakers Flashscore's commercial feed exposes. Default OFF — opt in explicitly. With the default 'primary' oddsCoveragePreset (1 GB request, single match_odds record per match) cost is $0.005 per match; 20 mainstream international bookmakers and ~860 market/scope rows are nested inside that one record. Use balanced/extended/global/max for additional regional bookmakers (each geo adds one extra match_odds record per match). Pinnacle is not in Flashscore's bookmaker network — validated across 186 request patterns.", "default": false }, "news": { "title": "News", "type": "boolean", "description": "Include public participant or competition news metadata where available. Default ON.", "default": true }, "liveRankings": { "title": "Live rankings", "type": "boolean", "description": "Include tennis live ranking projections from public ral_* feeds when available.", "default": false }, "articleContent": { "title": "Article content", "type": "boolean", "description": "Include the full body text on news_article records. Default ON. Set to false to keep only metadata (title, summary, public URL).", "default": true }, "raw": { "title": "Raw payloads", "type": "boolean", "description": "Include raw payloads for internal debugging only. Public dataset output removes raw payload fields.", "default": false } }, "default": { "commentary": false, "events": false, "highlights": false, "statistics": false, "lineups": false, "h2h": false, "momentum": false, "odds": false, "news": true, "liveRankings": false, "articleContent": true, "raw": false } }, "includeRaw": { "title": "Include raw payloads", "type": "boolean", "description": "Backward-compatible alias for include.raw. Raw payloads are disabled by default, only for internal debugging, and are removed from public dataset output.", "default": false }, "acknowledgeRawHighMemory": { "title": "Acknowledge raw + high-fan-out high-memory combination", "type": "boolean", "description": "Acknowledge that combining include.raw=true with oddsCoveragePreset=\"extended\"/\"global\"/\"max\" is high-memory. Intermediate records retain every HTTP response body until they are stripped at dataset push time, and these presets fan out odds requests across 20/28/48 geos respectively. The 2026-05-20 performance audit measured peak RAM near 1 GB on this combination, which can OOM-kill a standard 1-2 GB Actor tier. Leave this off (the default) and the parser will reject the high-RAM combination with a clear error. Set to true to opt in explicitly when you know what you are doing.", "default": false }, "maxItems": { "title": "Maximum results", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Maximum number of dataset items to output across the whole run, not per locale/category. Bookmakers mode defaults to 1000 when omitted because the catalog contains more than 100 geo entries. For news article runs, use Maximum news items per task when each locale/category needs its own cap.", "default": 50 }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Lower values are more polite and stable. Higher values may increase cost and failures.", "default": 2 }, "requestDelayMs": { "title": "Delay between requests in ms", "minimum": 0, "maximum": 10000, "type": "integer", "description": "Politeness delay between requests/pages.", "default": 1000 }, "locale": { "title": "Locale", "type": "string", "description": "Language/locale preference for public pages where applicable.", "default": "en" }, "timezone": { "title": "Timezone", "type": "string", "description": "IANA timezone used for date feed requests, such as UTC, Europe/Lisbon or America/New_York. Output timestamps remain ISO UTC.", "default": "UTC" }, "dryRun": { "title": "Dry run", "type": "boolean", "description": "Estimate tasks and billing events without extracting paid detail data.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Optional Apify proxy configuration. Do not use proxies to bypass access controls or evade restrictions." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```