# Flashscore Results: Match Listings & Historical Data (`extractify-labs/flashscore-results`) Actor

Extract match results from Flashscore tournaments and teams. Get scores, dates, teams, leagues, and more for football, basketball, and other sports.

- **URL**: https://apify.com/extractify-labs/flashscore-results.md
- **Developed by:** [Extractify Labs](https://apify.com/extractify-labs) (community)
- **Categories:** News, Other
- **Features:** Limited permissions
- **Stats:** 37 total users, 4 monthly users, 100.0% runs succeeded, 0 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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Flashscore Results: Match Listings & Historical Data

Extract complete match results from [Flashscore](https://www.flashscore.com) tournaments and team pages — no proxy required. Build historical match datasets, populate sports analytics dashboards, or feed prediction models with scores, team metadata, and tournament context. Supports **football** and **basketball** (fully tested); other Flashscore sports may also work.

*Built by [Extractify Labs](https://apify.com/extractify-labs). Last updated: 2026-04-26.*

***

### Key Features

- **Extract historical football and basketball results** from any Flashscore tournament page (e.g. Premier League, La Liga, NBA).
- **Monitor team match history** across multiple seasons using team result URLs.
- **Auto-detect page type** — mix tournament and team URLs in the same run; the actor handles both and returns the same structured output.
- **Multi-tournament team histories** — when using a team URL, each match is tagged with its correct tournament name and country, even when the team played in multiple competitions.
- **Filter by match status** — return only finished results, or include scheduled and live matches too.
- **Optional team logos** — enable `includeImages` to add CDN logo URLs per match.
- **Fast, direct extraction** via Flashscore's ninja feed endpoint — no browser, no proxy required.
- **Pagination handled automatically** — fetches all available pages for each URL; you control the total cap with `maxItems`.

***

### When to Use This Actor

| Use Case | Recommended Setup |
|----------|-------------------|
| Build all-time Premier League results dataset | Tournament URL, `maxItems: null` (unlimited) |
| Get a team's full match history | Team URL, `maxItems: null` |
| Recent season snapshot (top 100) | Tournament URL, `maxItems: 100` (default) |
| Finished matches only | `matchStatuses: ["finished"]` (default) |
| Include upcoming fixtures | `matchStatuses: ["all"]` |
| Include team logos | `includeImages: true` |
| Multi-league run | Multiple tournament or team URLs in `startUrls` |

**Typical scenarios:**

- **Historical dataset pipelines:** Feed complete match results into a database, spreadsheet, or data warehouse for long-term analysis.
- **Betting and prediction models:** Populate training data with historical scores, team identifiers, and tournament context.
- **Sports dashboards:** Display a team's recent form or a league's full results table with live-updated data.
- **Automated match reporting:** Trigger downstream workflows (notifications, reports) when new results appear.
- **Cross-tournament team analysis:** Pull a team's entire Flashscore history across all competitions in a single run.

***

### How It Works

1. You provide one or more Flashscore results page URLs in `startUrls`.
2. The actor automatically detects whether each URL is a **tournament results page** or a **team results page**.
3. For each URL it fetches the Flashscore ninja feed directly (no browser, no proxy).
4. Match rows are parsed, filtered by `matchStatuses`, and yielded as structured JSON items.
5. Pagination continues until no more matches are available, or `maxItems` is reached.

**Supported URL patterns:**

- Tournament: `https://www.flashscore.com/{sport}/{country}/{tournament}/results/`
  Example: `https://www.flashscore.com/football/england/premier-league/results/`
- Team: `https://www.flashscore.com/{sport}/team/{team-slug}/{team-id}/results/`
  Example: `https://www.flashscore.com/team/manchester-city/xSfcViB0/results/`

***

### Supported Sports

| Sport | Status |
|-------|--------|
| **Football** | Fully tested — all fields including `round_name` |
| **Basketball** | Fully tested — all fields except `round_name` (not available in basketball feed) |
| Other sports (tennis, hockey, volleyball, handball, etc.) | May work — not guaranteed; actor logs a warning for untested sports |

***

### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `startUrls` | array of URLs | required | One or more Flashscore results page URLs. The actor auto-detects tournament vs. team pages. You can mix both types in the same run. Example tournament URL: `https://www.flashscore.com/football/england/premier-league/results/`. Example team URL: `https://www.flashscore.com/team/manchester-city/xSfcViB0/results/`. |
| `maxItems` | integer | `100` | Maximum number of match results to return across all URLs. Set to `null` or leave blank for complete historical data (longer run time). Minimum: 1. |
| `matchStatuses` | array of strings | `["finished"]` | Filter results by match status. Accepted values: `"finished"`, `"live"`, `"scheduled"`, `"all"`. Use `["all"]` to include matches of any status. Invalid values are silently dropped; if all values are invalid, defaults to `["finished"]`. |
| `includeImages` | boolean | `false` | Include team logo URLs (`home_team_logo_url`, `away_team_logo_url`) in each result. Image URLs are direct CDN links. Disabled by default to keep payload size small. |

**Sample input (JSON):**

```json
{
  "startUrls": [
    "https://www.flashscore.com/football/england/premier-league/results/",
    "https://www.flashscore.com/team/manchester-city/xSfcViB0/results/"
  ],
  "maxItems": 50,
  "matchStatuses": ["finished"],
  "includeImages": false
}
```

***

### Output Fields

Each match record contains up to 23 fields. Required fields are always present; optional fields may be absent if the data is not available in the feed.

| Field | Type | Example | When Available |
|-------|------|---------|----------------|
| `match_id` | string | `"YBkFXzhf"` | Always |
| `match_url` | string (URL) | `"https://www.flashscore.com/match/football/aston-villa-W00wmLO0/brentford-xYe7DwID/?mid=YBkFXzhf"` | Always |
| `match_date` | string (ISO 8601 UTC) | `"2026-02-01T14:00:00+00:00"` | Always |
| `match_status` | string | `"finished"` | Always. One of: `finished`, `live`, `scheduled`, `unknown`. |
| `home_team_name` | string | `"Aston Villa"` | Always |
| `home_team_id` | string | `"W00wmLO0"` | Always |
| `home_team_slug` | string | `"aston-villa"` | Always |
| `home_team_short_name` | string | `"AST"` | Always |
| `home_team_logo_url` | string (URL) | `"https://static.flashscore.com/res/image/data/UHchCEVH-jwz95gs0.png"` | Only when `includeImages: true` |
| `away_team_name` | string | `"Brentford"` | Always |
| `away_team_id` | string | `"xYe7DwID"` | Always |
| `away_team_slug` | string | `"brentford"` | Always |
| `away_team_short_name` | string | `"BRE"` | Always |
| `away_team_logo_url` | string (URL) | `"https://static.flashscore.com/res/image/data/..."` | Only when `includeImages: true` |
| `score_home` | integer | `0` | Finished matches only; absent for scheduled and live |
| `score_away` | integer | `1` | Finished matches only; absent for scheduled and live |
| `tournament_name` | string | `"Premier League"` | Always |
| `tournament_id` | string | `"dYlOSQOD"` | Always |
| `tournament_url` | string (URL) | `"https://www.flashscore.com/football/england/premier-league/"` | Always |
| `country_name` | string | `"England"` | Always |
| `round_name` | string | `"Round 24"` | Football tournaments only; absent for other sports and some cup competitions |
| `sport_name` | string | `"football"` | Always |
| `source_url` | string (URL) | `"https://www.flashscore.com/football/england/premier-league/results/"` | Always; identifies which input URL produced this result |

**Sample output record:**

```json
{
  "match_id": "YBkFXzhf",
  "match_url": "https://www.flashscore.com/match/football/aston-villa-W00wmLO0/brentford-xYe7DwID/?mid=YBkFXzhf",
  "match_date": "2026-02-01T14:00:00+00:00",
  "match_status": "finished",
  "home_team_name": "Aston Villa",
  "home_team_id": "W00wmLO0",
  "home_team_slug": "aston-villa",
  "home_team_short_name": "AST",
  "away_team_name": "Brentford",
  "away_team_id": "xYe7DwID",
  "away_team_slug": "brentford",
  "away_team_short_name": "BRE",
  "score_home": 0,
  "score_away": 1,
  "tournament_name": "Premier League",
  "tournament_id": "dYlOSQOD",
  "tournament_url": "https://www.flashscore.com/football/england/premier-league/",
  "country_name": "England",
  "round_name": "Round 24",
  "sport_name": "football",
  "source_url": "https://www.flashscore.com/football/england/premier-league/results/"
}
```

***

### Limitations

- **This actor is not affiliated with Flashscore.** It reads from Flashscore's publicly accessible feed endpoints.
- **Multi-sport support:** Fully tested with football and basketball. Other sports (tennis, hockey, volleyball, etc.) may work but are not guaranteed. The actor logs a warning for untested sports and attempts extraction; if the sport ID cannot be determined, the URL is skipped.
- **`round_name` field:** Available for football tournaments where the feed includes round labels. Absent for basketball and other sports, and for some cup competitions that do not use explicit round labels.
- **`maxItems` is a global cap, not a per-URL cap.** In a multi-URL run, whichever feed responds first may fill the cap before other URLs are fully processed. If you need a fixed number of results from each URL, run the actor once per URL.
- **Historical data depth:** The actor returns all results available in Flashscore's feed for the given URL. Flashscore's own data retention determines how far back results are available; the actor does not impose any additional limit beyond `maxItems`.
- **Scores are absent for non-finished matches.** The `score_home` and `score_away` fields are only populated when a match has finished. They are absent (not `null`) for scheduled and live matches.
- **This is not a live-scores actor.** If you need near-real-time match monitoring, use the [Flashscore Live Matches](https://apify.com/extractify-labs/flashscore-live-matches) actor instead.

***

### FAQ

**Q: What is the difference between tournament and team modes?**

A: A **tournament URL** (e.g. `https://www.flashscore.com/football/england/premier-league/results/`) returns all matches played in that competition for the current or historical season. A **team URL** (e.g. `https://www.flashscore.com/team/manchester-city/xSfcViB0/results/`) returns all of that team's matches across all competitions — the `tournament_name` and `country_name` fields identify which competition each match belongs to. You can mix both URL types in a single run.

**Q: Can I fetch all historical results for a team or tournament?**

A: Yes. Set `maxItems` to `null` (or leave it blank) to remove the cap. The actor will paginate through all available results. Run time will be longer for teams or tournaments with many years of history.

**Q: Can I include upcoming fixtures, not just finished results?**

A: Yes. Set `matchStatuses` to `["all"]` to include scheduled, live, and finished matches. You can also select specific statuses, for example `["finished", "scheduled"]`.

**Q: Does this actor work with sports other than football and basketball?**

A: It may. The actor is fully tested with football and basketball. For other Flashscore sports (tennis, hockey, volleyball, handball, etc.), provide a valid Flashscore results URL in the standard format and the actor will attempt extraction. It logs a warning for untested sports. Results are not guaranteed and `round_name` will typically be absent.

**Q: Is pagination automatic?**

A: Yes. The actor handles all pagination internally. You do not need to specify page numbers or offsets — just provide the results URL and set `maxItems` to control the total number of results you want.

**Q: Why did some URLs in my multi-URL run produce fewer results than expected?**

A: `maxItems` is a global cap across all URLs in the run, not a per-URL cap. If one URL fills the cap first, results from other URLs may be limited or absent. To get a fixed count from each URL, run the actor once per URL.

***

### No Proxy Required

This actor fetches data directly from Flashscore's internal feed endpoint — no residential or datacenter proxies needed. You are charged only for standard Apify compute time, not proxy bandwidth. This makes it significantly cheaper to run at scale compared to browser-based scrapers.

***

### Related Actors

- [Flashscore: Match Listings, Scores & Fixtures](https://apify.com/extractify-labs/flashscore-extractor) — Today's matches, live scores, and upcoming fixtures in a ±7-day window
- [Flashscore Live Matches](https://apify.com/extractify-labs/flashscore-live-matches) — Real-time live match monitoring
- [Flashscore H2H](https://apify.com/extractify-labs/flashscore-h2h) — Head-to-head match history between two teams

***

### Support & Issues

- Report bugs or request features on [GitHub](https://github.com/web-crawling/apify-flashscore-results/issues).
- For general questions, use the actor's Discussion tab on the Apify Store page.

# Changelog

This Actor's version history is a separate document: https://apify.com/extractify-labs/flashscore-results/changelog.md

# Actor input Schema

## `startUrls` (type: `array`):

One or more Flashscore results page URLs. The actor detects the page type automatically — you can mix tournament and team URLs in the same run.

**Tournament URL example:** `https://www.flashscore.com/football/england/premier-league/results/`
**Team URL example:** `https://www.flashscore.com/team/manchester-city/xSfcViB0/results/`

Fully tested with football and basketball. Other sports (hockey, tennis, volleyball, etc.) may work but are not guaranteed — the actor logs a warning for untested sports.

## `maxItems` (type: `integer`):

Maximum number of match results to return across all URLs. Set higher or leave blank for full historical data (longer run time). For a single recent season, 100–500 is usually sufficient.

## `matchStatuses` (type: `array`):

Filter results by match status. Accepted values: `"finished"`, `"live"`, `"scheduled"`, `"all"`. Use `["all"]` to include matches of any status.

## `includeImages` (type: `boolean`):

Include team logo URLs (`home_team_logo_url`, `away_team_logo_url`) in each result. Image URLs are direct CDN links to `https://static.flashscore.com/res/image/data/{filename}`. Disabled by default to reduce payload size for data-pipeline use cases.

## Actor input object example

```json
{
  "startUrls": [
    "https://www.flashscore.com/football/england/premier-league/results/",
    "https://www.flashscore.com/team/manchester-city/xSfcViB0/results/"
  ],
  "maxItems": 100,
  "matchStatuses": [
    "finished"
  ],
  "includeImages": false
}
```

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

// Prepare Actor input
const input = {
    "startUrls": [
        "https://www.flashscore.com/football/england/premier-league/results/",
        "https://www.flashscore.com/team/manchester-city/xSfcViB0/results/"
    ],
    "matchStatuses": [
        "finished"
    ],
    "includeImages": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("extractify-labs/flashscore-results").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 = {
    "startUrls": [
        "https://www.flashscore.com/football/england/premier-league/results/",
        "https://www.flashscore.com/team/manchester-city/xSfcViB0/results/",
    ],
    "matchStatuses": ["finished"],
    "includeImages": False,
}

# Run the Actor and wait for it to finish
run = client.actor("extractify-labs/flashscore-results").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 '{
  "startUrls": [
    "https://www.flashscore.com/football/england/premier-league/results/",
    "https://www.flashscore.com/team/manchester-city/xSfcViB0/results/"
  ],
  "matchStatuses": [
    "finished"
  ],
  "includeImages": false
}' |
apify call extractify-labs/flashscore-results --silent --output-dataset

```

## MCP server setup

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

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/JMRBW8vIWXdq8lE2D/builds/7vj3UyeBRoqAYpdxe/openapi.json