# Flashscore H2H - Football Head-to-Head Results (`extractify-labs/flashscore-h2h`) Actor Given any Flashscore match URL, extract the full head-to-head history between the two teams - dates, scores, competition, and team details. No proxy required. Returns up to 20 fields per historical match in structured JSON. - **URL**: https://apify.com/extractify-labs/flashscore-h2h.md - **Developed by:** [Extractify Labs](https://apify.com/extractify-labs) (community) - **Categories:** Other, Social media, News - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 results 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 H2H — Football Head-to-Head Results Given any Flashscore match URL, this actor extracts the full list of historical head-to-head results between the two teams — scores, dates, competition, and team metadata — in a single HTTP request per URL. No proxy required. Paste one or more match URLs, get 20 structured fields per H2H result. ### What does this actor extract? This actor extracts 20 fields per historical H2H match, including scores, dates, competition name, team names with logos, and a direct link to each match on Flashscore. It also returns `competition_name`, `country_name`, and `competition_abbreviation` — enabling you to filter results by competition (e.g. Premier League only) after the run. | Field | Type | Example | |-------|------|---------| | `match_id` | string | `"U3M9iQJ6"` | | `match_url` | string (URL) | `"https://www.flashscore.com/match/football/manchester-city-Wtn9Stg0/arsenal-hA1Zm19f/?mid=U3M9iQJ6"` | | `match_date` | string (ISO 8601 UTC) | `"2026-04-19T15:30:00+00:00"` | | `competition_name` | string | `"Premier League"` | | `competition_abbreviation` | string | `"PL"` | | `country_name` | string | `"England"` | | `country_id` | string | `"198"` | | `home_team_name` | string | `"Manchester City"` | | `home_team_id` | string | `"Wtn9Stg0"` | | `home_team_slug` | string | `"manchester-city"` | | `home_team_short_name` | string | `"Manchester City"` | | `home_team_logo_url` | string (URL) | `"https://static.flashscore.com/res/image/data/UXcqj7HG-lQuhqN8N.png"` | | `away_team_name` | string | `"Arsenal"` | | `away_team_id` | string | `"hA1Zm19f"` | | `away_team_slug` | string | `"arsenal"` | | `away_team_short_name` | string | `"Arsenal"` | | `away_team_logo_url` | string (URL) | `"https://static.flashscore.com/res/image/data/pfchdCg5-vcNAdtF9.png"` | | `score_home_goals` | integer | `2` | | `score_away_goals` | integer | `1` | | `score_combined` | string | `"2:1"` | | `match_status_code` | string | `"3"` | Note: `home_team_logo_url` and `away_team_logo_url` are ready-to-use CDN image URLs — embed them directly in any dashboard or front-end display. ### Who is this for? - **Betting and odds analysts:** Feed the last N meetings between two teams into your pre-match model before a Premier League fixture. `competition_name` and `match_date` let you filter to relevant competition context and recency. - **Data scientists building football prediction models:** Use historical H2H score margins, competition context, and home/away split as input features for match outcome prediction. - **Fantasy sports and gaming operators:** Populate fixture preview cards with historical results between the two teams playing this week. - **Sports journalists and content teams:** Automate the "last five meetings" summary block in match preview articles, complete with dates, scores, and competition names. ### How to use it 1. Open any football match page on [Flashscore](https://www.flashscore.com). For example: the Arsenal vs Manchester City match. 2. Copy the full URL from your browser's address bar. The URL must include the `?mid=` query parameter — it looks like this: `https://www.flashscore.com/match/football/arsenal-hA1Zm19f/manchester-city-Wtn9Stg0/?mid=U3M9iQJ6` 3. Paste the URL into the `matchUrls` input field. You can add multiple URLs to retrieve H2H history for several fixtures in one run — each URL produces results for a separate pair of teams. 4. (Optional) Set `daysBack` to limit results to the last N days (default: 365). Set to `0` to return all historical results regardless of date. 5. (Optional) Set `maxItems` to cap the total number of H2H results returned across all URLs. 6. Click **Start**. The actor makes one HTTP request per URL and returns all matching H2H results. **Important:** If you copy a URL from a different tab or before the match page has fully loaded, the `?mid=` parameter may be missing. The actor will log a warning and skip that URL, then continue processing any remaining valid URLs. If all URLs are invalid, the actor stops immediately — go back to each match page in your browser, copy the URL again, and re-run. **Sample input (JSON):** ```json { "matchUrls": [ "https://www.flashscore.com/match/football/arsenal-hA1Zm19f/manchester-city-Wtn9Stg0/?mid=U3M9iQJ6" ], "daysBack": 365, "maxItems": 10 } ```` ### Input parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | `matchUrls` | array of strings | Yes | See prefill | One or more full Flashscore match page URLs. Each URL must include the `?mid=` query parameter — copy it directly from your browser's address bar after opening a match page. URLs missing `?mid=` are skipped with a warning; the actor fails only if the list is empty. Minimum: 1 item. | | `daysBack` | integer | No | `365` | Only return H2H results from the last N days. Set to `0` to return all results regardless of date. Filtering is applied after fetching — it does not reduce the number of HTTP requests made. Minimum: 0. | | `maxItems` | integer | No | — (all results) | Maximum total number of H2H results to return across all URLs, applied after `daysBack` filtering. Leave unset to return all available results. Minimum: 1. | ### Output format A complete H2H match record from a live Arsenal vs Manchester City run: ```json { "match_id": "U3M9iQJ6", "match_url": "https://www.flashscore.com/match/football/manchester-city-Wtn9Stg0/arsenal-hA1Zm19f/?mid=U3M9iQJ6", "match_date": "2026-04-19T15:30:00+00:00", "competition_name": "Premier League", "competition_abbreviation": "PL", "country_name": "England", "country_id": "198", "home_team_name": "Manchester City", "home_team_id": "Wtn9Stg0", "home_team_slug": "manchester-city", "home_team_short_name": "Manchester City", "home_team_logo_url": "https://static.flashscore.com/res/image/data/UXcqj7HG-lQuhqN8N.png", "away_team_name": "Arsenal", "away_team_id": "hA1Zm19f", "away_team_slug": "arsenal", "away_team_short_name": "Arsenal", "away_team_logo_url": "https://static.flashscore.com/res/image/data/pfchdCg5-vcNAdtF9.png", "score_home_goals": 2, "score_away_goals": 1, "score_combined": "2:1", "match_status_code": "3" } ``` All dates are in ISO 8601 UTC format (`+00:00` suffix). `score_home_goals` and `score_away_goals` are native integers, not strings. `match_status_code` `"3"` means the match is finished — all H2H results in the feed are finished matches. ### No proxy required This actor fetches data directly from Flashscore's internal feed endpoint using a single HTTP request per URL. No residential or datacenter proxy is needed. You pay only for Apify compute — a typical run costs under $0.01. Each run makes exactly one HTTP request per match URL provided. This means the actor is fast, reliable, and unlikely to encounter rate limiting. ### Use cases - **Build a pre-match H2H report for a betting model:** Pull the full meeting history between two Premier League teams before a fixture. Filter to `competition_name == "Premier League"` post-run to isolate only top-flight encounters. - **Populate a sports analytics database with historical H2H records:** Run once per match you care about, store the structured output in your database. The `match_url` field links back to each historical match on Flashscore for further drill-down. - **Automate match preview content:** Feed H2H summary data into a template engine to generate "last N meetings" sections for football journalism or fan content. - **Generate features for a football prediction model:** Use `score_home_goals`, `score_away_goals`, `competition_name`, and `match_date` to derive features such as average goal difference, home advantage, and recency weighting. - **Display a head-to-head widget on a fantasy sports platform:** Use `home_team_logo_url`, `away_team_logo_url`, `score_combined`, and `match_date` to build a visual H2H card without additional API calls for team logos. - **Batch multiple fixtures in a single run:** Add several match URLs to `matchUrls` to retrieve H2H history for multiple fixtures at once — the actor processes each URL in sequence and combines all results in a single dataset. ### Limitations This actor extracts the **Overall** head-to-head section only. It does not extract: - Home/away sub-section H2H results (e.g. "last 5 meetings at the Etihad") - Team form rows (last 50 matches per individual team) - Match statistics (possession, shots, cards, corners) - Betting odds or bookmaker lines - Player-level data or lineups - Matches where the Flashscore H2H feed returns no results (some early-season or rarely-played fixtures may have no H2H history — the actor exits cleanly with zero items in this case) The actor only extracts football (soccer) H2H data. The H2H feed URL pattern used by this actor is not confirmed to work for other sports. ### FAQ #### Where do I find the match URL with the `?mid=` parameter? Open any football match page directly on [Flashscore](https://www.flashscore.com) — click through to the match, not just a team or league page. Once the match page is open, copy the full URL from your browser's address bar. It should look like: `https://www.flashscore.com/match/football/team-a-ID/team-b-ID/?mid=XXXXXXXX` The `?mid=` parameter is the match identifier. If your URL does not contain `?mid=`, you are not on the match page — navigate to the specific match and copy again. You can add as many URLs as you like to `matchUrls` to retrieve H2H history for multiple fixtures in one run. #### Does `daysBack=0` return all historical results? Yes. Setting `daysBack` to `0` disables the date filter entirely and returns every H2H result available in the Flashscore feed, regardless of how old it is. A live test on Arsenal vs Manchester City with `daysBack=0` returned 50 results spanning many years. The default value is `365`, which limits results to the past year. #### Does this actor work for all sports or only football? This actor is designed and tested for football (soccer) only. The H2H feed endpoint used internally is specific to the football match format. Other sports on Flashscore have different feed structures and are not supported. #### How many historical H2H matches does Flashscore show? It varies by fixture. A live test on Arsenal vs Manchester City returned 50 H2H results. Flashscore typically shows the most recent 50 meetings for well-matched fixtures. Some less frequently-played fixtures may return fewer results or none at all. #### Does this actor require a proxy? No. The actor makes a direct HTTP request to Flashscore's feed endpoint. No proxy subscription is required. You pay only for Apify compute time. #### Is scraping Flashscore legal? Web scraping publicly available data is generally permitted for personal use and research purposes. Users are responsible for complying with [Flashscore's terms of service](https://www.flashscore.com/page/terms-of-service/) and applicable local laws. Apify's [legal guidelines on web scraping](https://apify.com/legal/web-scraping) provide further context. #### How is this different from the Flashscore Match Listings actor? The [Flashscore Match Listings, Scores & Fixtures](https://apify.com/extractify-labs/flashscore-extractor) actor returns today's live scores and fixtures across a 14-day window — it is for discovering matches across many teams and leagues. This actor does the opposite: given one or more specific match URLs, it returns all historical meetings between those specific pairs of teams. They complement each other: use Match Listings to find the upcoming fixture, then run this actor to get the H2H history for the same pair of teams. #### Can I use `maxItems` to get only the most recent H2H results? Yes. Flashscore returns H2H results in reverse chronological order (most recent first). `maxItems` is applied after `daysBack` filtering. Setting `maxItems: 5` with `daysBack: 0` returns the 5 most recent meetings of all time. Setting `maxItems: 5` with `daysBack: 365` returns up to 5 meetings from the past year. Leave `maxItems` unset to get all results that pass the date filter. ### Related actors - [Flashscore: Match Listings, Scores & Fixtures](https://apify.com/extractify-labs/flashscore-extractor) — Extract today's match listings, live scores, and upcoming fixtures across football and basketball. Use this to discover matches; use the H2H actor for historical context on a specific pair of teams. - [Flashscore Tennis Matches](https://apify.com/extractify-labs/flashscore-tennis-matches) — Extract tennis match data from Flashscore covering ATP, WTA, ITF, and Challenger circuits. - [Flashscore Live Matches](https://apify.com/extractify-labs/flashscore-live-matches) — In-depth live football match data including events, statistics, and lineups updated in real time. # Actor input Schema ## `matchUrls` (type: `array`): One or more Flashscore match page URLs. Each URL must include the ?mid= query parameter — copy directly from your browser's address bar after opening a match page. Add multiple URLs to retrieve H2H history for several fixtures in one run. ## `daysBack` (type: `integer`): Only return H2H results from the last N days. Set to 0 to return all results regardless of date. ## `maxItems` (type: `integer`): Maximum number of overall head-to-head match results to return. Leave blank to return all available results. ## Actor input object example ```json { "matchUrls": [ "https://www.flashscore.com/match/football/arsenal-hA1Zm19f/manchester-city-Wtn9Stg0/?mid=U3M9iQJ6" ], "daysBack": 365 } ``` # Actor output Schema ## `results` (type: `string`): No description # 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 = { "matchUrls": [ "https://www.flashscore.com/match/football/arsenal-hA1Zm19f/manchester-city-Wtn9Stg0/?mid=U3M9iQJ6" ] }; // Run the Actor and wait for it to finish const run = await client.actor("extractify-labs/flashscore-h2h").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 = { "matchUrls": ["https://www.flashscore.com/match/football/arsenal-hA1Zm19f/manchester-city-Wtn9Stg0/?mid=U3M9iQJ6"] } # Run the Actor and wait for it to finish run = client.actor("extractify-labs/flashscore-h2h").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 '{ "matchUrls": [ "https://www.flashscore.com/match/football/arsenal-hA1Zm19f/manchester-city-Wtn9Stg0/?mid=U3M9iQJ6" ] }' | apify call extractify-labs/flashscore-h2h --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=extractify-labs/flashscore-h2h", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Flashscore H2H - Football Head-to-Head Results", "description": "Given any Flashscore match URL, extract the full head-to-head history between the two teams - dates, scores, competition, and team details. No proxy required. Returns up to 20 fields per historical match in structured JSON.", "version": "0.0", "x-build-id": "hCJcgRJ4NCAwBz50u" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/extractify-labs~flashscore-h2h/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-extractify-labs-flashscore-h2h", "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/extractify-labs~flashscore-h2h/runs": { "post": { "operationId": "runs-sync-extractify-labs-flashscore-h2h", "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/extractify-labs~flashscore-h2h/run-sync": { "post": { "operationId": "run-sync-extractify-labs-flashscore-h2h", "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": [ "matchUrls" ], "properties": { "matchUrls": { "title": "Match URLs", "minItems": 1, "type": "array", "description": "One or more Flashscore match page URLs. Each URL must include the ?mid= query parameter — copy directly from your browser's address bar after opening a match page. Add multiple URLs to retrieve H2H history for several fixtures in one run.", "items": { "type": "string" } }, "daysBack": { "title": "Days back", "minimum": 0, "type": "integer", "description": "Only return H2H results from the last N days. Set to 0 to return all results regardless of date.", "default": 365 }, "maxItems": { "title": "Maximum Items", "minimum": 1, "type": "integer", "description": "Maximum number of overall head-to-head match results to return. Leave blank to return all available results." } } }, "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 } } } } } } } } } } ```