# Flashscore Basketball Scraper - Live Scores, Quarters & Stats (`clearfetch/flashscore-basketball-scraper`) Actor

Scrape basketball games from Flashscore: fixtures, live scores, final results, quarter-by-quarter and overtime scores, team data and full match statistics. NBA, EuroLeague, NCAA and every domestic league. No proxy, no login.

- **URL**: https://apify.com/clearfetch/flashscore-basketball-scraper.md
- **Developed by:** [Nada Hanad](https://apify.com/clearfetch) (community)
- **Categories:** Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 games

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?

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 Basketball Scraper - Live Scores, Quarters & Stats

Get basketball data from Flashscore as clean JSON: fixtures for the days you choose, live scores, final results,
and the score in every quarter and overtime period. Per game you can also pull the full statistics sheet, from
field-goal percentages to rebounds, assists and turnovers. NBA, EuroLeague, NCAA and every domestic league
Flashscore covers. No login, no API key and no proxy.

### What data you get

**Games mode** returns one row per game:

- **Quarter-by-quarter scores** that add up to the final score, plus any overtime periods as their own entries.
- **Status resolved from Flashscore's own stage codes**, not guessed: scheduled, live, finished, postponed,
  cancelled or interrupted, plus `stageDetail` naming the exact stage (`FIRST_QUARTER`, `THIRD_QUARTER`,
  `EXTRA_TIME`, `AWARDED`).
- **Competition**: name, country, phase such as Play Offs, plus IDs and the Flashscore URL.
- **Teams**: name, Flashscore team ID and slug, three-letter code and logo.
- **`raw`**: all 43 original feed fields for the game, so nothing is lost if you need something we did not map.

**Game details mode** takes match IDs and returns, per game:

- **Period scores** straight from the source.
- **Full statistics** split by period and group: field goals attempted, made and percentage, three pointers,
  free throws, offensive and defensive rebounds, assists, turnovers, steals and blocks. 100 rows for the
  example below.
- **Head to head**: recent form for both teams and their previous meetings.

### How to use

1. Choose **Games** mode and set **Days** (0 is today, -1 yesterday, 1 tomorrow; add several for a range).
2. Optionally narrow by status, by country, or with a regular expression on the competition name such as `nba`.
3. Run it, then export as JSON, CSV or Excel, or read it from the API. For a deeper look at one game, run the
   Actor again in **Game details** mode with the `matchId` values you got back.

### Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `mode` | string | `matches` | `matches` for fixtures, live scores and results; `matchDetails` for period scores, statistics and head to head. |
| `days` | array | `["0"]` | Day offsets from today, from -7 to 7. Several entries are fetched in one run and deduplicated. |
| `status` | array | all | Keep only `scheduled`, `live`, `finished`, `postponed`, `cancelled` or `interrupted`. |
| `countries` | array | all | Keep only these countries or regions, for example USA, Spain, Europe. |
| `tournamentFilter` | string | — | Case-insensitive regular expression on the full competition name, e.g. `euroleague|eurocup`. |
| `matchIds` | array | — | Details mode: match IDs such as `nm66nX6U`, or full `flashscore.com/match/...` URLs. |
| `details` | array | all three | Details mode: `summary`, `statistics`, `h2h`. |
| `maxItems` | integer | `0` | Stop after this many rows; 0 means no limit. |
| `maxConcurrency` | integer | `5` | Parallel requests in details mode. |
| `timeoutSecs` | integer | `30` | Per-request timeout. |
| `token` | string | — | Advanced. Overrides the feed signature, which the Actor otherwise discovers by itself. |
| `proxyConfiguration` | object | off | Optional. Not needed in normal use. |

### Output example

One game from a **games** run (the `raw` object with all 43 feed fields is omitted here for readability):

```json
{
  "matchId": "nm66nX6U",
  "url": "https://www.flashscore.com/match/nm66nX6U/",
  "sport": "basketball",
  "status": "finished",
  "stage": "finished",
  "stageDetail": "FINISHED",
  "stageCode": 3,
  "stageDetailCode": 3,
  "startTime": "2026-09-04T23:30:00.000Z",
  "lastUpdate": "2026-09-05T00:57:35.000Z",
  "note": null,
  "tournament": {
    "name": "LNB",
    "fullName": "PARAGUAY: LNB - Clausura",
    "country": "Paraguay",
    "phase": "Clausura",
    "id": "dddz4h2L",
    "stageId": "SK32QUiJ",
    "path": "/basketball/paraguay/lnb/",
    "url": "https://www.flashscore.com/basketball/paraguay/lnb/"
  },
  "home": {
    "name": "Capiata Bulls",
    "fullName": "Capiata Bulls",
    "id": "OSTxMXDD",
    "slug": "capiata-bulls",
    "url": "https://www.flashscore.com/team/capiata-bulls/OSTxMXDD/",
    "code": "CAP",
    "image": null
  },
  "away": {
    "name": "San Alfonzo",
    "fullName": "San Alfonzo",
    "id": "jZLOqy6K",
    "slug": "san-alfonzo",
    "url": "https://www.flashscore.com/team/san-alfonzo/jZLOqy6K/",
    "code": "SAN",
    "image": "https://static.flashscore.com/res/image/data/Mw8KczVH-dINMEfSG.png"
  },
  "score": {
    "home": 89,
    "away": 126,
    "quarters": [
      {
        "period": "Q1",
        "home": 20,
        "away": 23
      },
      {
        "period": "Q2",
        "home": 27,
        "away": 33
      },
      {
        "period": "Q3",
        "home": 21,
        "away": 44
      },
      {
        "period": "Q4",
        "home": 21,
        "away": 26
      }
    ],
    "overtime": null
  },
  "winner": "away",
  "inPlay": false,
  "ok": true,
  "dayOffset": 0,
  "scrapedAt": "2026-09-05T14:39:09.824Z"
}
```

A **game details** item, trimmed to the first statistics rows:

```json
{
  "matchId": "nm66nX6U",
  "url": "https://www.flashscore.com/match/nm66nX6U/",
  "sport": "basketball",
  "ok": true,
  "summary": {
    "periods": [
      {
        "period": "1st Quarter",
        "home": 20,
        "away": 23
      },
      {
        "period": "2nd Quarter",
        "home": 27,
        "away": 33
      },
      {
        "period": "3rd Quarter",
        "home": 21,
        "away": 44
      },
      {
        "period": "4th Quarter",
        "home": 21,
        "away": 26
      }
    ]
  },
  "statistics": [
    {
      "period": "Match",
      "group": "Scoring",
      "name": "Field goals attempts",
      "home": "77",
      "away": "86"
    },
    {
      "period": "Match",
      "group": "Scoring",
      "name": "Field goals made",
      "home": "32",
      "away": "51"
    },
    {
      "period": "Match",
      "group": "Scoring",
      "name": "Field goals %",
      "home": "41.56%",
      "away": "59.3%"
    },
    {
      "period": "Match",
      "group": "Scoring",
      "name": "2-point field goals attempts",
      "home": "43",
      "away": "62"
    }
  ],
  "scrapedAt": "2026-09-05T14:39:23.412Z"
}
```

A game that cannot be found, or has no data yet, produces `{ "matchId": "...", "ok": false, "error": "..." }`
and is not charged.

### Pricing

- **$0.001 per game** in games mode. A normal day is a few hundred games worldwide, so well under a dollar for
  everything, or a few cents once you filter by country or competition.
- **$0.01 per game** in details mode, whatever number of sections you request. Period scores, the whole
  statistics sheet and both teams' recent form count as one charge.
- Games that fail or have no data are free. Runs on the Apify free plan.

### Use cases

- **Betting and trading models**: build a history of quarter splits, shooting percentages and pace, then keep it
  current with a scheduled daily run.
- **Live scoreboards and bots**: poll games mode for in-play scores and push updates to a site, app or Discord.
- **Fantasy basketball**: pull box-score style statistics per game.
- **Media and newsletters**: generate daily results digests with the quarter breakdown.
- **Research and machine learning**: label datasets across leagues, including overtime games and abandoned ones.
- **AI agents**: give an assistant a tool that answers "what was the score by quarter in last night's games".

### Integrations

```bash
curl -X POST "https://api.apify.com/v2/acts/clearfetch~flashscore-basketball-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"days": ["0"], "status": ["finished"]}'
```

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_TOKEN")
run = client.actor("clearfetch/flashscore-basketball-scraper").call(
    run_input={"days": ["0"], "status": ["finished"]}
)
for game in client.dataset(run["defaultDatasetId"]).iterate_items():
    quarters = " ".join(f"{q['home']}-{q['away']}" for q in game["score"]["quarters"] or [])
    print(game["home"]["name"], game["score"]["home"], "-", game["score"]["away"], game["away"]["name"], quarters)
```

Works with the Apify integrations for n8n, Make, Zapier, Google Sheets, Slack and webhooks, with scheduled runs,
and with AI agents through the Apify MCP server.

### FAQ

**Do I need a proxy?** No. The feed answers ordinary datacenter requests. A proxy input exists if you want one.

**Do I need a Flashscore account?** No. Nothing here requires a login or a cookie.

**Do the quarter scores always add up?** Yes, and the Actor's tests assert it on every finished game in the
fixture set. Overtime periods are returned separately so you can tell regulation from what followed.

**How fresh is the data?** Each run reads the feed live, so games in progress carry their current score.
Schedule a run every few minutes if you need a running scoreboard.

**What if Flashscore changes its feed signature?** The Actor discovers the current signature from the site on
every run and falls back to a known value, so a rotation does not break it. The `token` input is a last resort.

**Which sports does this cover?** Basketball. The same feed carries other sports; ask if you want one added.

**Is this legal?** It reads the same public endpoints a browser reads, with no login and no personal data.
Scores and results are facts. You are responsible for how you use the data, including any redistribution.

### Changelog

- **1.0.0** (2026-09) — first release: games mode with day ranges and status, country and competition filters;
  details mode with period scores, statistics and head to head; status resolved from Flashscore's own stage
  codes; automatic feed-signature discovery.

# Actor input Schema

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

"Games" returns one row per game for the days you choose. "Game details" takes match IDs and returns quarter scores, statistics and head-to-head for each one.

## `days` (type: `array`):

Which days to cover, as offsets from today: 0 is today, -1 yesterday, 1 tomorrow. Range -7 to 7. Add several entries to cover a range in one run.

## `status` (type: `array`):

Keep only games in these states. Leave empty for all. Status is resolved from Flashscore's own stage codes, so a game in the third quarter counts as live.

## `countries` (type: `array`):

Keep only competitions from these countries or regions, for example USA, Spain, Europe. Case-insensitive. Leave empty for all.

## `tournamentFilter` (type: `string`):

Optional case-insensitive regular expression matched against the full competition name, for example "nba" or "euroleague|eurocup".

## `matchIds` (type: `array`):

Match IDs such as "nm66nX6U", or full flashscore.com/match/... URLs. Only used in game details mode.

## `details` (type: `array`):

Sections to fetch per game. Leave empty for all three. Each game is charged once no matter how many sections you pick.

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

Stop after this many rows. 0 means no limit.

## `maxConcurrency` (type: `integer`):

Parallel requests in details mode.

## `timeoutSecs` (type: `integer`):

Give up on a single feed request after this many seconds.

## `token` (type: `string`):

Advanced. The Actor discovers Flashscore's feed signature automatically and falls back to a known value. Set this only if both stop working and you have a current signature.

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

Optional. The feed answers plain datacenter requests, so no proxy is needed in normal use.

## Actor input object example

```json
{
  "mode": "matches",
  "days": [
    "0"
  ],
  "status": [],
  "countries": [],
  "matchIds": [],
  "details": [],
  "maxItems": 0,
  "maxConcurrency": 5,
  "timeoutSecs": 30,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

In games mode, one row per game: status, tip-off time, competition with country, both teams, final score and the score in each quarter and overtime period. In game details mode, one row per game with its period scores, full statistics and head-to-head. Games with no data appear with ok=false and are not charged.

# 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 = {
    "days": [
        "0"
    ],
    "countries": [],
    "matchIds": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("clearfetch/flashscore-basketball-scraper").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 = {
    "days": ["0"],
    "countries": [],
    "matchIds": [],
}

# Run the Actor and wait for it to finish
run = client.actor("clearfetch/flashscore-basketball-scraper").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 '{
  "days": [
    "0"
  ],
  "countries": [],
  "matchIds": []
}' |
apify call clearfetch/flashscore-basketball-scraper --silent --output-dataset

```

## MCP server setup

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

```

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/uRITnxYdrFq13UufP/builds/nKcklhXj3ea9moNsj/openapi.json