# FlashScore Scraper Live (`statanow/flashscore-scraper-live`) Actor

Scrape FlashScore live scores, fixtures, results, odds, and match events across 16 sports. In historical mode, enrich each match with up to 100 recent games per team, detailed statistics, incidents, and mutual H2H. Export analytics-ready sports data to JSON, CSV, Excel, or the Apify API.

- **URL**: https://apify.com/statanow/flashscore-scraper-live.md
- **Developed by:** [statanow](https://apify.com/statanow) (community)
- **Categories:** News, Other, E-commerce
- **Stats:** 539 total users, 21 monthly users, 100.0% runs succeeded, 12 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.001 / result

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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 Live Scores API & Sports Data Scraper

Scrape live scores, fixtures, results, odds, match events, and historical sports
data from [FlashScore](https://www.flashscore.com/) across 16 sports.

Use **Live + historical snapshots** mode to enrich each current match with up to
**100 recent matches per team**, available head-to-head results, detailed
statistics, and incidents. Every match is returned as one structured,
analytics-ready record.

Use the structured JSON output in live-score apps, sports dashboards, betting
research, prediction models, match previews, Telegram bots, fantasy tools, and
automated reports. Run it without code in Apify Console or connect through the
Apify API, webhooks, schedules, Python, JavaScript, Make, Zapier, or n8n.

| ⚡ Fast live collection | 🧠 Analysis-ready history | 🏅 Multi-sport coverage |
|---|---|---|
| Read pre-collected history instead of scraping it during every request | Current match, team form, statistics, incidents, and H2H in one record | Football, basketball, tennis, hockey, and 12 more sports |

### 🆕 Live matches are now analytics-ready

The new `with-history` mode turns this live-score scraper into a practical
sports analytics tool. Instead of making hundreds of extra requests, you can
receive the current match together with recent form for both teams, mutual H2H,
historical scores, match statistics, and incidents in the same Dataset item.

This makes the output ready for team-form analysis, prediction features,
betting research, match previews, dashboards, bots, and AI workflows. Historical
coverage depends on the available pre-collected snapshot, so every enriched
record includes a clear `historical_snapshot_status`.

### ⚽ Why use this FlashScore scraper?

Just run the Actor and you instantly get:

- 🔗 League and stable FlashScore match ID
- 🏟️ Home and away teams or players
- ⏱️ Live score, match clock, odds, and status
- 📅 Kick-off or scheduled start time
- 📜 Event history with goals, cards, substitutions, and period summaries
- 📚 Up to 100 historical matches per team with available statistics
- 🤝 Mutual head-to-head history when FlashScore provides it
- 📦 Structured sports data in JSON, CSV, Excel, XML, RSS, or HTML
- ⌚ API endpoints, scheduling, exports, integrations, and webhooks

Use this FlashScore scraper to monitor games, build dashboards, automate alerts,
support betting research, analyze match momentum, calculate team form, or feed
current and historical context into machine-learning and AI workflows.

### ⚡ Live and historical output modes

The Actor opens FlashScore's **All Games** view for the selected sport and dates,
collects every available match URL, and returns one structured Dataset item per
match.

Choose between two output modes:

| Mode | Best for | Data returned |
|---|---|---|
| `standard` | Live-score feeds and lightweight monitoring | Match ID, teams, league, scores, status, start time, odds, and event timeline |
| `with-history` | Analytics, team-form research, H2H analysis, and ML pipelines | Everything in `standard`, plus the pre-collected historical snapshot for that match |

Historical enrichment is storage-first: the live run reads an existing snapshot
by the stable FlashScore match ID. It does **not** re-scrape hundreds of past
match pages while the user waits.

### ✨ Key features

- **Live scores, fixtures, and results** for selectable dates from 7 days ago to 7 days ahead.
- **16 sports** or all supported sports in one run.
- **Up to 100 recent matches for the home team and 100 for the away team**.
- **Mutual H2H history** when FlashScore provides head-to-head records.
- **Detailed historical statistics**, including sport-specific metrics.
- **Historical incidents**, scores, competitions, dates, and source URLs.
- **Odds and match event timelines** for current matches when available.
- **Historical year filter** for smaller, analysis-specific datasets.
- **Clear coverage statuses** such as `ready`, `partial`, and `not_found`.
- **JSON, CSV, Excel, XML, RSS, and HTML exports** through Apify Dataset.
- **API, scheduling, webhooks, and integrations** included with the Apify platform.

### 📊 What FlashScore sports data can you scrape?

#### 📡 Current match data

Each match can include:

| | | | |
|---|---|---|---|
| 🏠 Home team | 🛫 Away team | ⚽ Home score | 🥅 Away score |
| 📡 Match status | ⏱️ Status time | 📅 Start time | 🌍 League |
| 📄 Period summaries | 🏟️ Score and time | 🥅 Player name | 🏃 Action and side |
| 💰 Odds | 🆔 Match ID | 🗂 Historical snapshot | ✅ Coverage status |

| Field | Description |
|---|---|
| `match_id` | Stable FlashScore match identifier |
| `home_team`, `away_team` | Competing teams or players |
| `home_score`, `away_score` | Current or final score |
| `status`, `status_time` | Scheduled, live, interrupted, or finished state and match clock |
| `start_time` | Displayed kick-off or start time |
| `league` | Country, competition, league, or tournament |
| `odds` | Available pre-match home/draw/away decimal odds |
| `history` | Goals, cards, substitutions, period summaries, and other available events |
| `historical_snapshot_status` | Historical-data availability and quality status |
| `historical_snapshot` | Full historical context in `with-history` mode |

Fields that FlashScore does not expose for a particular sport or match are
omitted or returned empty. Availability differs by sport, competition, and
match state.

#### 🗂️ Historical snapshot data

When `Output mode` is set to `with-history`, `historical_snapshot` can include:

- current match identity and source metadata;
- home team's recent matches;
- away team's recent matches;
- mutual head-to-head matches;
- match dates, teams, leagues, status, and scores;
- period scores and normalized sport-specific statistics;
- incidents such as goals, cards, and substitutions when available;
- collection timestamps, counts, warnings, and errors;
- the applied `Oldest historical year` filter summary.

The Actor preserves the complete stored snapshot. It does not flatten or drop
historical match fields.

### 🏅 Supported sports

| | | | |
|---|---|---|---|
| ⚽ Football | 🏀 Basketball | 🎾 Tennis | 🏒 Ice hockey |
| ⚾ Baseball | 🏐 Volleyball | 🏈 American football | 🤾 Handball |
| 🏏 Cricket | 🥅 Futsal | 🏉 Rugby union | 🏉 Rugby league |
| 🏸 Badminton | 🏓 Table tennis | 🎯 Darts | 🎱 Snooker |

Select **All supported sports** to collect every sport in parallel.

### 🚀 How to scrape FlashScore data

1. Open the Actor in [Apify Store](https://apify.com/statanow/flashscore-scraper-live).
2. Select the dates, sport, output mode, and oldest historical year.
3. Click **Start** — the historical snapshot store is configured automatically.
4. Open **Storage → Dataset → All fields** to inspect complete records.
5. Export the Dataset or use its API endpoint in your application.

For a quick test, start with one sport and today only. Selecting all sports or
multiple dates produces more results and takes longer.

### ⬇️ Input options

The visual form contains only four user-facing settings:

| Input | Type | Default | Description |
|---|---|---:|---|
| `dayOffsets` | Multi-select | `0` | Dates relative to today, from `-7` to `+7` |
| `sport` | Select | `football` | One supported sport or `all` |
| `mode` | Select | `with-history` | Live match data only or live data with historical snapshots |
| `historyFromYear` | Integer | `1949` | Keep historical matches from January 1 of this year through today |

`0` means today, `-1` means yesterday, and `1` means tomorrow. Multiple values
can be selected in a single run.

#### 🌍 All sports example

```json
{
  "dayOffsets": ["-1", "0", "1"],
  "sport": "all",
  "mode": "with-history",
  "historyFromYear": 2020
}
```

### ⬆️ Output example

One Dataset item represents one current match. This shortened example shows the
relationship between current and historical data:

```json
{
  "match_id": "AbC123xY",
  "home_team": "Team A",
  "away_team": "Team B",
  "home_score": 2,
  "away_score": 1,
  "status": "Live",
  "status_time": "2nd Half - 71'",
  "start_time": "29.08.2026 18:00",
  "league": "ENGLAND: Premier League",
  "odds": {
    "home": 1.82,
    "draw": 3.6,
    "away": 4.4
  },
  "history": [
    {
      "kind": "event",
      "time": "57",
      "score": "2 - 1",
      "side": "home",
      "player": "Player A",
      "action": "Goal"
    }
  ],
  "historical_snapshot_status": "ready",
  "historical_snapshot": {
    "schema_version": 1,
    "current_match_id": "AbC123xY",
    "historical_data": {
      "home_team": {
        "team_name": "Team A",
        "matches": [
          {
            "match_id": "Past001",
            "sport": "football",
            "date": "2026-08-23",
            "league": "ENGLAND: Premier League",
            "home_team": "Team A",
            "away_team": "Team C",
            "score": {"home": 3, "away": 1, "raw": "3-1"},
            "statistics": {"Ball Possession": {"home": "61%", "away": "39%"}},
            "incidents": []
          }
        ]
      },
      "away_team": {"team_name": "Team B", "matches": []},
      "h2h": {"matches": []}
    },
    "meta": {
      "status": "ready",
      "history_limit_requested": 100,
      "counts": {"home_matches": 100, "away_matches": 100, "h2h_matches": 8}
    },
    "live_history_filter": {
      "from_year": 2018,
      "before": 208,
      "after": 208,
      "filtered_out": 0,
      "unparseable_dates_kept": 0
    }
  }
}
```

The exact statistics keys depend on the sport. Football may include possession,
shots, corners, fouls, and cards; tennis can include aces and service metrics;
basketball and hockey expose their own relevant statistics when available.

#### Standard live record example

In `standard` mode, the same Dataset stays compact and omits the historical
snapshot fields:

```json
{
  "match_id": "Mkz9mcpL",
  "home_team": "Morocco U17",
  "away_team": "Brazil U17",
  "home_score": 1,
  "away_score": 1,
  "status": "Live",
  "status_time": "2nd Half - 58'",
  "start_time": "21.11.2025 16:45",
  "league": "WORLD: World Cup U17 - Play Offs",
  "history": [
    {
      "kind": "event",
      "time": "16",
      "score": "0 - 1",
      "side": "away",
      "player": "Dell (Ruan Pablo)",
      "action": "Goal"
    },
    {
      "kind": "event",
      "time": "57",
      "side": "home",
      "player": "Eddaoudi A.",
      "action": "Yellow card"
    }
  ]
}
```

### 🧭 Historical snapshot statuses

| Status | Meaning |
|---|---|
| `ready` | Snapshot exists and all available historical data was collected |
| `partial` | Snapshot exists, but some historical details could not be collected |
| `failed` | The scheduler could not build a complete snapshot |
| `available` | A compatible snapshot exists without an explicit scheduler status |
| `not_found` | No snapshot currently exists for this match ID |
| `missing_match_id` | The current match did not provide a usable ID |
| `invalid_snapshot` | Stored data did not match the expected snapshot contract |
| `lookup_error` | The snapshot store could not be read after retries |

A missing or failed historical lookup never removes valid current match data.
Use `historical_snapshot_status` to filter or score coverage in downstream
workflows.

### 🗄️ Dataset, Key-Value Store, and full fields

- **Default Dataset:** one full item per match, including
  `historical_snapshot` in `with-history` mode.
- **Dataset Overview:** a compact table for quick inspection. Switch to
  **All fields** to see the complete nested snapshot.
- **KVS `OUTPUT`:** a compact run summary. To avoid record-size limits, it does
  not duplicate every full historical snapshot.

![FlashScore sports data scraper output](https://i.imgur.com/ycW8xnv.png)

To download complete JSON without the compact view, use:

```text
https://api.apify.com/v2/datasets/DATASET_ID/items?clean=true&format=json
```

Do not add `view=overview` when you need `historical_snapshot`.

### 🔌 Use the FlashScore API endpoint

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/statanow~flashscore-scraper-live/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dayOffsets": ["0"],
    "sport": "football",
    "mode": "with-history",
    "historyFromYear": 2020
  }'
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("statanow/flashscore-scraper-live").call(run_input={
    "dayOffsets": ["0"],
    "sport": "football",
    "mode": "with-history",
    "historyFromYear": 2020,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["home_team"], item["away_team"])
```

#### ⚡ Standby HTTP endpoint

When Standby mode is enabled, call the Actor as a continuously available HTTP
API. `sport` is required; `days` accepts one value or a comma-separated list:

```text
GET https://YOUR-ACTOR-STANDBY-URL/matches?sport=football&days=-1,0,1&mode=with-history&historyFromYear=2020
```

The Standby response contains the run metadata and a `matches[]` array with full
snapshots inline. The regular Actor run stores the same matches as individual
Dataset items, which is usually better for exporting large result sets.

### 💡 Use cases

- Build live-score websites, widgets, and mobile apps.
- Calculate team form, scoring trends, totals, and streaks.
- Prepare features for sports prediction and machine-learning models.
- Create pre-match or in-play research dashboards.
- Enrich sports news, match previews, and automated summaries.
- Power Telegram, Discord, Slack, and notification bots.
- Monitor competitions across multiple sports and dates.
- Feed AI agents with structured current and historical match context.

The Actor provides source data, not betting advice or guaranteed predictions.
Users are responsible for their own analysis and decisions.

### 💰 Pricing

The Actor uses result-based pricing: you pay for match records successfully
returned by the run. Both modes return one Dataset item per current match; the
historical mode enriches that item when a compatible snapshot is available.
Check the **Pricing** tab on the Actor page for the current rate and any Apify
plan discounts before starting a large run.

The number of results depends on the selected dates, sport, and matches available
on FlashScore. Use Apify's maximum run charge option when you need a strict cost
limit.

### ❓ FAQ

#### Does it return only matches that are live right now?

No. The Actor uses FlashScore's All Games view. Depending on the selected day,
the results can include scheduled, live, interrupted, postponed, and finished
matches.

#### How much match history is included?

The scheduler requests up to 100 historical matches for each team and available
mutual H2H records. FlashScore may expose fewer records for some teams, players,
competitions, or sports.

#### Why is `historical_snapshot` missing even when the match is present?

Check `historical_snapshot_status`. `not_found` means the scheduler does not yet
have a snapshot for that match. `lookup_error` indicates a storage access issue.
The current match fields remain available in both cases.

#### Why do I see `ready` but not the historical object in Apify Console?

The **Overview** table intentionally shows only compact fields. Open **All
fields**, or download Dataset JSON without `view=overview`.

#### Can I export the data?

Yes. Apify Dataset supports JSON, CSV, Excel, XML, RSS, and HTML exports, plus
API access and integrations.

#### Can I schedule automatic updates?

Yes. Use Apify Schedules to run the Actor at your preferred interval and
webhooks to notify another application when a run succeeds or fails.

# Actor input Schema

## `dayOffsets` (type: `array`):

Choose which days to scrape. 0 = Today, -1 = Yesterday, 1 = Tomorrow. Select multiple days to scrape several dates.

## `sport` (type: `string`):

Choose a sport for matches scraping.

## `mode` (type: `string`):

standard keeps the current live-only behavior; with-history additionally reads scheduler snapshots by match ID.

## `historyFromYear` (type: `integer`):

Include every historical match from January 1 of this year through today. Use 1949 for the full currently available depth.

## `workers` (type: `integer`):

Requested match-detail concurrency. In Live + history mode v4 applies a memory-aware safety cap based on ACTOR\_MEMORY\_MBYTES.

## `sportConcurrency` (type: `integer`):

Requested parallel sports when sport=all. Live + history caps this to 1-2 on typical memory sizes to keep snapshots bounded.

## `historyLookupConcurrency` (type: `integer`):

Requested KVS lookup concurrency. Live + history v4 applies a memory-aware cap and bounded streaming batches to prevent OOM.

## `historyStorageRequestsPerSecond` (type: `integer`):

Hidden global KVS pacing maximum kept below Apify's 200 requests/second limit.

## Actor input object example

```json
{
  "dayOffsets": [
    "0"
  ],
  "sport": "football",
  "mode": "with-history",
  "historyFromYear": 1949,
  "workers": 64,
  "sportConcurrency": 16,
  "historyLookupConcurrency": 64,
  "historyStorageRequestsPerSecond": 150
}
```

# Actor output Schema

## `overview` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("statanow/flashscore-scraper-live").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("statanow/flashscore-scraper-live").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).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 statanow/flashscore-scraper-live --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,statanow/flashscore-scraper-live"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/rdOwbSNd2e3a5nTug/builds/C32WVjChPeOZy90Vb/openapi.json