# Flashscore Live Matches (`khadinakbar/flashscore-live-matches`) Actor

Scrape Flashscore live match scores — in-progress matches with running score and minute, filtered by sport, country and league. HTTP-only, MCP-ready.

- **URL**: https://apify.com/khadinakbar/flashscore-live-matches.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** News, Automation, MCP servers
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 match records

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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 Matches

Flashscore Live Matches is an Apify Actor that returns **in-progress Flashscore matches** with their running score and minute. It reads a sport's daily feed and filters to the matches live right now, and can also return scheduled fixtures or finished results for the same day window. You pick a sport, optionally narrow by country or league, and receive one structured JSON record per match.

It is HTTP-only against Flashscore's own data feed, so it is fast and cheap with no headless browser. It is MCP-ready for AI agents and built for teams and bots that want a clean "what's live right now" answer in a single call.

### Best fit and connected workflows

Use when your workflow starts with **"which matches are live right now"** and ends with clean, machine-readable live scores.

Common routing patterns:

- Daily live-score pulls for a sport (default `statuses: ["live"]`)
- Live matches for one country (`country: "England"`) or one competition (`league: "Premier League"`)
- Today's completed results or tonight's fixtures on the same feed (`statuses: ["live","finished"]`)
- Scheduled re-runs to keep a scoreboard or alert bot fresh

A typical workflow chain: **start with** this live board to see what is in progress, **then** pass `matchId` values downstream for anything richer. For full match detail, standings, and head-to-head, **then use** the sibling [flashscore-scraper](https://apify.com/khadinakbar/flashscore-scraper). This Actor is designed as a focused standalone workflow for the in-progress board on its own.

### Example workflow

A Discord scoreboard bot **starts** with "which matches are live," **then** runs this Actor on a schedule (for example every 5 minutes), **then** renders each `match` record with home team, away team, current score, and `minute` to the channel. A sports analyst can do the same and export the rows to a spreadsheet for a live market snapshot.

### When to reach for it

- Building a **live scoreboard, betting dashboard, or Discord/Telegram/Slack bot**.
- **Sports analysts** who need the current in-play board for a sport or league.
- **AI agents** that want a one-call sports-data tool: sport in, live JSON out.

When a workflow needs tick-by-tick streaming, standings tables, or per-match statistics and lineups, the natural next step is the all-in-one **flashscore-scraper** sibling rather than this narrower board.

### Input

| Field | Type | Purpose |
|---|---:|---|
| `sport` | string | Sport to scrape. Defaults to `football`. |
| `dayOffsets` | array | Relative days to scan, e.g. `[0]` (today) or `[-1, 0, 1]`. Default `[0]`. |
| `date` | string | Exact single day `YYYY-MM-DD`, within 7 days. Overrides `dayOffsets`. |
| `statuses` | array | Statuses to return. Default `["live"]`. |
| `country` | string | Case-insensitive match on the display country/region, e.g. `England`. |
| `league` | string | Case-insensitive match on the league name, e.g. `Premier League`. |
| `maxResults` | integer | Hard cap on billable records. Default `100`. |
| `language` | string | Feed label language code, e.g. `en`. Default `en`. |
| `sportId` | integer | Advanced numeric Flashscore sport ID for sports outside the dropdown. |
| `proxyConfiguration` | object | Proxy settings, defaulting to Apify Proxy. |

#### Focused JSON example — live football now

```json
{
  "sport": "football",
  "dayOffsets": [0],
  "statuses": ["live"],
  "maxResults": 100,
  "language": "en"
}
```

#### JSON example — tonight's English fixtures

```json
{
  "sport": "football",
  "dayOffsets": [0, 1],
  "statuses": ["scheduled"],
  "country": "England",
  "maxResults": 50
}
```

### Output

One dataset record per matching match. Live records carry the running score and minute.

| Field | Type | Purpose |
|---|---:|---|
| `matchId` | string | Flashscore 8-char match ID, the record key. |
| `recordType` | string | Always `match`. |
| `sport` / `sportId` | string / integer | Sport name and numeric ID. |
| `country` / `league` | string | Competition country and league name. |
| `homeTeam` / `awayTeam` | string | Team names. |
| `homeScore` / `awayScore` | integer | Current score. |
| `status` | string | `live`, `scheduled`, `finished`, and so on. |
| `minute` | integer | Running minute/period for live matches (null otherwise). |
| `startTime` | string | Kick-off time ISO 8601 UTC. |
| `matchUrl` | string | Flashscore match page URL. |

#### Live record example

```json
{
  "recordType": "match",
  "matchId": "n3KhBdY7",
  "sport": "football",
  "sportId": 1,
  "country": "Asia",
  "league": "AFC Champions League Women - Preliminary",
  "homeTeam": "April W (Prk)",
  "awayTeam": "Kharaatsai W (Mon)",
  "homeScore": 7,
  "awayScore": 0,
  "statusCode": 2,
  "status": "live",
  "minute": 13,
  "startTime": "2026-08-17T09:00:00.000Z",
  "matchUrl": "https://www.flashscore.com/match/n3KhBdY7/"
}
```

### How it works

The Actor reads Flashscore's public JSON-style feed over plain HTTP. List feeds are fetched per sport and day offset, parsed into match entities, then filtered to the requested statuses and any country or league match. For live matches the in-progress minute is read from the feed, so you see the live state rather than only a static flag. Feed requests are retried with backoff, and if a route is unavailable mid-run the Actor returns everything it already collected and reports the partial result honestly rather than failing the whole run.

### Pricing

Flashscore Live Matches uses **Pay per event**, plus standard platform usage (compute and proxy). The live **Pricing tab** on the Actor is the source of truth for current rates and billing details.

The billable events are:

- **Actor start** — $0.00005
- **Match record** — $0.003 per matching match returned

A bounded pull capped at `maxResults: 100` charges about $0.30 in match-record events (100 match records × $0.003), plus the small start event and usage. Every run prints its maximum cost before charging, and `maxResults` is a hard cap on billable records.

### Use with AI agents (MCP)

This Actor is available through Apify MCP as the Apify Actor `khadinakbar/flashscore-live-matches`.

**Tool description:** retrieve in-progress Flashscore match scores with running score and minute, optionally filtered by sport, country, league, or additional match statuses. Returns one structured JSON record per match for live-score, scoreboard, and sports-bot workflows.

Example agent prompt:

> Pull today's live football matches. Return each match with home team, away team, current score, and the current minute, and list only matches that are live right now.

Output interpretation and provenance:

- `match` records are live scores (default), or scheduled/finished rows when those statuses are selected
- `matchId` uniquely identifies each match and links to `matchUrl`
- `minute` is the current in-play minute for live records only
- `status` distinguishes live from scheduled and finished
- Data comes from Flashscore's public feed; scope is the selected sport, day(s), statuses, and any country/league filter
- `language` changes labels only; it does not change which matches are returned

Cost, scope, and pagination guidance:

- Use `maxResults` to cap dataset size and billable records
- For a busy sport, raise `maxResults` to capture the full live board
- Re-run on a schedule for a live scoreboard (the Actor does not stream)
- For the richer all-in-one surface (standings, H2H, match stats), then use the sibling `flashscore-scraper`

### API example

```bash
curl -X POST "https://api.apify.com/v2/acts/khadinakbar~flashscore-live-matches/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "football",
    "dayOffsets": [0],
    "statuses": ["live"],
    "maxResults": 20
  }'
```

### Downstream and scope notes

- The feed window spans about −7 to +7 days; for older history use match IDs via the sibling `flashscore-scraper`.
- `minute` is approximate per sport: football and other in-play sports expose it, and some niche sports may return null while still live.
- Results are a snapshot at fetch time; schedule re-runs for a live scoreboard.
- Country/league filters are substring matches on the displayed names, not stable codes.
- To confirm a fetched board, read the returned records back from the dataset and validate that `status` and `minute` match what is shown on the Flashscore match pages.

### Legal

This Actor reads publicly available match data from Flashscore's feed. Only collect and use data in ways that comply with Flashscore's terms of service and applicable law. Game-related data is informational.

### Builder's note

I built this as a deliberately narrow companion to the all-in-one `flashscore-scraper`. Betting and sports-dashboard users kept asking for just the live board: a single, fast, cheap call they could run on a cron or from an agent without pulling fixtures, standings, and match detail they did not need. The feed's in-progress minute is the field that makes live data useful, so I surfaced it directly rather than hiding it behind a generic `status` flag. I designed it to be a focused standalone workflow on the same proven HTTP feed stack the sibling actor has used in production on the Store for some time.

# Actor input Schema

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

The sport to scrape live matches for, e.g. 'football', 'tennis', or 'basketball'. Defaults to 'football'. This is the sport whose daily feed is read and filtered for in-progress matches. NOT a free-text search box — pick a supported Flashscore sport name or use sportId for an advanced numeric ID.

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

Relative days to scan for matches. 0 = today, -1 = yesterday, 1 = tomorrow. Defaults to \[0] (today's matches). Matches currently in progress can appear on neighbouring days near midnight in some timezones, so include -1 and 1 to be safe. Each offset triggers one feed request; results are merged and de-duplicated by matchId is NOT performed, so overlapping days may repeat a match.

## `date` (type: `string`):

A single calendar day in YYYY-MM-DD format (e.g. '2026-08-17') to scan instead of dayOffsets. Must be within 7 days of today because Flashscore only serves that feed window. Overrides dayOffsets when both are set. NOT a range — for multiple days use dayOffsets.

## `statuses` (type: `array`):

Which match statuses to return. Defaults to \['live'] so only in-progress matches with a running score and minute are returned. Add 'scheduled' for upcoming fixtures or 'finished' for final results on the same days. Each selected status is matched against the match's derived status; unsupported status strings are ignored.

## `country` (type: `string`):

Case-insensitive substring filter on the match's country or region, e.g. 'England' or 'Spain'. Limits the returned live matches to leagues under that country. Empty means no country filter. NOT a list of codes — use the display name shown on Flashscore (e.g. 'England', not 'GB').

## `league` (type: `string`):

Case-insensitive substring filter on the league or tournament name, e.g. 'Premier League' or 'La Liga'. Limits the returned live matches to that competition. Empty means no league filter. NOT a league ID — use the display name shown on Flashscore.

## `maxResults` (type: `integer`):

Hard cap on billable match records produced this run. Protects your budget and bounds the run cost. Defaults to 100. Set higher to capture all live matches for a busy sport, or lower for a quick live check.

## `language` (type: `string`):

Flashscore feed language code for team/competition labels, e.g. 'en', 'es', 'de'. Defaults to 'en'. Changes label language only; it does not change which matches are returned. NOT a country or locale object — a single two-letter code.

## `sportId` (type: `integer`):

Numeric Flashscore sport ID to scrape when the sport is not in the dropdown (e.g. a niche sport). Overrides the sport dropdown when both are set. football=1, tennis=2, basketball=3. NOT required for the listed sports — leave empty to use the sport dropdown.

## `proxyConfiguration` (type: `object`):

Proxy settings, defaulting to Apify Proxy (datacenter). The Flashscore feed tolerates the standard Apify datacenter proxy. Override only if you hit rate limits and need residential IPs.

## Actor input object example

```json
{
  "sport": "football",
  "dayOffsets": [
    0
  ],
  "statuses": [
    "live"
  ],
  "maxResults": 1,
  "language": "en",
  "sportId": 1,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `matches` (type: `string`):

Live-match records (and scheduled/finished rows when selected) produced by the run.

## `summary` (type: `string`):

Detailed terminal diagnostics and billing counters.

## `output` (type: `string`):

Stable machine-readable terminal outcome and delivery counters.

# 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 = {
    "sport": "football",
    "dayOffsets": [
        0
    ],
    "date": "",
    "statuses": [
        "live"
    ],
    "country": "",
    "league": "",
    "maxResults": 1,
    "language": "en",
    "sportId": 1,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/flashscore-live-matches").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 = {
    "sport": "football",
    "dayOffsets": [0],
    "date": "",
    "statuses": ["live"],
    "country": "",
    "league": "",
    "maxResults": 1,
    "language": "en",
    "sportId": 1,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/flashscore-live-matches").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 '{
  "sport": "football",
  "dayOffsets": [
    0
  ],
  "date": "",
  "statuses": [
    "live"
  ],
  "country": "",
  "league": "",
  "maxResults": 1,
  "language": "en",
  "sportId": 1,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call khadinakbar/flashscore-live-matches --silent --output-dataset

```

## MCP server setup

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

```

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/7t3EXuPaCFMCKMXrh/builds/eaKygT9GJX4T5ZMwx/openapi.json