# Sofascore Scraper (`automation-lab/sofascore-live-events-statistics-scraper`) Actor

Export live and scheduled Sofascore events with teams, tournaments, scores, status, venue, round, and available match statistics for sports analysis.

- **URL**: https://apify.com/automation-lab/sofascore-live-events-statistics-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Sports, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

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

## Sofascore Scraper

Export scheduled and live Sofascore events as clean JSON records for sports analysis, dashboards, reporting, and recurring monitoring.

The Actor collects teams, tournament context, scheduled start, match status, current or final score, venue, round, and available match statistics. It supports date-based discovery, live-event discovery, and exact SofaScore event IDs or match URLs.

No SofaScore login or buyer API key is required.

### What can you do with this Sofascore scraper?

- Download fixtures for a sport and calendar date.
- Capture matches that are live when a run starts.
- Export one known match by event ID or public URL.
- Add possession, shots, expected goals, passes, cards, and other available statistics.
- Filter discovered records by status, team name, or tournament name.
- Schedule runs and compare datasets to monitor score and status changes.

This Actor returns event records. It does not place bets, predict outcomes, stream video, or modify SofaScore data.

### Who is it for?

**Sports analysts** can build fixture and result tables without manually copying match pages.

**Data engineers** can schedule a consistent Sofascore data export into a warehouse or spreadsheet.

**Publishers and dashboard teams** can monitor status and score fields for internal reporting workflows.

**Researchers** can collect available match-level statistics for descriptive analysis.

Always check the source rights and your intended use before redistributing data.

### Why use this Actor?

- Three targeting routes: date, live, and exact event.
- One normalized output shape across sports.
- Statistics are included in the event record at no separate event charge.
- Stable event IDs make snapshots easy to compare.
- `maxItems` limits output and cost.
- Empty filters return an empty dataset rather than fabricated records.
- Invalid inputs fail clearly instead of silently changing scope.

### Getting started

1. Open the Actor input.
2. Choose **Events by date** or **Live events**.
3. Enter a SofaScore sport slug such as `football`, `basketball`, or `tennis`.
4. For date mode, enter a `YYYY-MM-DD` date.
5. Keep **Include match statistics** enabled when you need detailed metrics.
6. Set `maxItems` to your desired result cap.
7. Run the Actor.
8. Download the dataset as JSON, CSV, Excel, XML, or RSS through Apify.

To target one match, provide `eventIds` or `eventUrls`. Exact targets take priority over discovery mode.

### Input parameters

| Field | Type | Default | Purpose |
| --- | --- | --- | --- |
| `mode` | string | `date` | Discover events by `date` or fetch events live now. |
| `sport` | string | `football` | Lowercase SofaScore sport slug. |
| `date` | string | today | Date in `YYYY-MM-DD` format for date mode. |
| `eventIds` | string array | empty | Exact numeric SofaScore event IDs. |
| `eventUrls` | string array | empty | Public match URLs containing `#id:<event ID>`. |
| `includeStatistics` | boolean | `true` | Fetch statistics where SofaScore makes them available. |
| `status` | string | `all` | Keep `all`, `scheduled`, `live`, or `finished` events. |
| `team` | string | empty | Case-insensitive home/away team substring. |
| `tournament` | string | empty | Case-insensitive competition substring. |
| `maxItems` | integer | `100` | Save at most 1–500 matched events. |

#### Date export input

```json
{
  "mode": "date",
  "sport": "football",
  "date": "2026-08-11",
  "includeStatistics": false,
  "maxItems": 25
}
```

#### Exact match statistics input

```json
{
  "eventUrls": [
    "https://www.sofascore.com/football/match/usa-bosnia-and-herzegovina/EObszUb#id:12812992"
  ],
  "includeStatistics": true,
  "maxItems": 1
}
```

### Output fields

| Field | Description |
| --- | --- |
| `eventId` | Stable SofaScore event identifier. |
| `eventUrl` | Public match URL reconstructed from source IDs and slugs. |
| `sport` | Sport slug. |
| `startTime` | Scheduled UTC start time. |
| `status` | Machine-readable match state. |
| `statusDescription` | Human-readable status. |
| `tournament` | Competition ID, name, and slug. |
| `category` | Geographic/category context. |
| `homeTeam`, `awayTeam` | Team IDs, names, and slugs. |
| `score` | Current/final and period scores where available. |
| `round` | Tournament round when available. |
| `venue` | Venue or stadium when available. |
| `country` | Country or geographic category. |
| `hasStatistics` | Whether the run found statistics for this match. |
| `statistics` | Normalized period/group/name/home/away values. |
| `sourceMode` | `date`, `live`, or `event`. |
| `scrapedAt` | UTC extraction timestamp. |

Source fields can be null when SofaScore has not published them.

### Output example

This shortened record reflects the Actor's real output shape:

```json
{
  "eventId": 12812992,
  "sport": "football",
  "startTime": "2026-07-02T00:00:00.000Z",
  "status": "finished",
  "tournament": { "id": 16, "name": "FIFA World Cup", "slug": "world-championship" },
  "homeTeam": { "id": 4724, "name": "USA", "slug": "usa" },
  "awayTeam": { "id": 4479, "name": "Bosnia & Herzegovina", "slug": "bosnia-and-herzegovina" },
  "score": { "home": 2, "away": 0, "period1Home": 1, "period1Away": 0 },
  "hasStatistics": true,
  "statistics": [
    { "group": "Match overview", "name": "Ball possession", "home": "48%", "away": "52%", "period": "ALL" }
  ],
  "sourceMode": "event"
}
```

### How much does it cost to export Sofascore events?

The Actor uses pay-per-event pricing:

- one `start` event per run;
- one `item` event for each matched event saved to the dataset;
- no separate charge for the statistics included inside that event record.

At the current Bronze tier, the start is **$0.005** and each event is **$0.001104**. Examples:

| Saved events | Estimated Actor charge |
| ---: | ---: |
| 1 | $0.006104 |
| 25 | $0.032600 |
| 100 | $0.115400 |

Apify applies the price tier associated with your plan. Infrastructure usage and plan rules are shown in Console before and after each run. Use the result limit to control the maximum saved-item cost.

### Scheduling a live score monitor

1. Save a Task with `mode: "live"`.
2. Select the sport and a practical result cap.
3. Enable statistics if downstream analysis needs them.
4. Add an Apify schedule, for example every 10 minutes.
5. Use `eventId` as the merge key in your database.
6. Compare `status`, `score`, `statistics`, and `scrapedAt` between snapshots.

A run is a snapshot, not a persistent stream. Your schedule frequency determines monitoring frequency.

### API usage with cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~sofascore-live-events-statistics-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"live","sport":"football","maxItems":10}'
```

To wait for results:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~sofascore-live-events-statistics-scraper/run-sync-get-dataset-items?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"date","sport":"football","date":"2026-08-11","maxItems":5}'
```

### JavaScript integration

```js
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/sofascore-live-events-statistics-scraper').call({
  eventIds: ['12812992'],
  includeStatistics: true,
  maxItems: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items[0]);
```

### Python integration

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("automation-lab/sofascore-live-events-statistics-scraper").call(
    run_input={"mode": "live", "sport": "basketball", "maxItems": 20}
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### MCP and AI-agent use

Add this Actor to Claude Code through Apify MCP:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/sofascore-live-events-statistics-scraper"
```

#### Claude Desktop, Cursor, and VS Code setup

Use this same MCP configuration in Claude Desktop, Cursor, or VS Code:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/sofascore-live-events-statistics-scraper"
    }
  }
}
```

Example prompts:

- “Export today's football fixtures from Sofascore, limit 30.”
- “Fetch event 12812992 and summarize its available match statistics.”
- “Get the current live basketball event snapshot as JSON.”

### Limits and source behavior

- Statistics do not exist for every event.
- Upcoming matches commonly have an empty `statistics` array.
- Live availability changes minute by minute.
- A sport/date combination may naturally return no events.
- SofaScore can add, remove, or rename fields and routes.
- Date discovery may make several lightweight source requests to cover categories.
- The Actor retries transient failures with bounded backoff.
- A persistent access challenge fails the run rather than returning a false empty dataset.
- The Actor does not download images, video, commentary, odds, incidents, or lineups.

### Troubleshooting

#### Why is `statistics` empty?

The event may be scheduled, too early in live play, or not covered with detailed metrics. Check `hasStatistics`. Try a completed event known to have a Statistics tab.

#### Why did a live run return few or zero records?

Live mode is a point-in-time snapshot. The selected sport may have no active matches. Use date mode for fixtures, or run again at a time when the competition is active.

#### Why did my team filter return nothing?

The filter is a case-insensitive substring over the home and away team names returned by SofaScore. Remove the filter, inspect the canonical spelling, and retry.

#### Can I submit any URL?

No. `eventUrls` accepts public `sofascore.com` match URLs containing an event ID. Other domains and non-event URLs fail validation.

### Legality and responsible use

This Actor accesses publicly available sports information. You are responsible for complying with SofaScore's terms, applicable database rights, copyright, privacy law, and the rules governing your downstream use.

Do not use the Actor to overload the source, bypass access controls, misrepresent official data, or make regulated betting decisions without independent verification. Keep schedules and result caps proportionate to your purpose.

### FAQ

#### Is this an official Sofascore API?

No. This is an independent Apify Actor that normalizes public SofaScore data. It is not endorsed by SofaScore.

#### Does it support multiple sports?

Yes, when SofaScore exposes the sport through its public routes. Use the lowercase sport slug. Football, basketball, tennis, ice hockey, baseball, and cricket are common examples.

#### Are live updates pushed continuously?

No. Each run produces one snapshot. Use an Apify schedule or API calls for recurring snapshots.

#### Can I export CSV or Excel?

Yes. Open the default dataset and select the desired Apify export format.

#### Are statistics charged separately?

No. Available statistics are included in each charged event record.

#### Does it require a proxy setting?

No buyer proxy input is exposed. The Actor manages its public data route internally.

### Related Actors

For a source-independent sports workflow, explore other sports-data Actors from [automation-lab on Apify](https://apify.com/automation-lab). Choose the source that matches your analysis rather than merging records with incompatible IDs or field definitions.

# Actor input Schema

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

Choose events scheduled on a date or events that are live now. Explicit event IDs/URLs take priority.

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

Lowercase SofaScore sport slug, such as football, basketball, tennis, ice-hockey, baseball, or cricket.

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

Calendar date for date mode in YYYY-MM-DD format. Defaults to today when omitted.

## `eventIds` (type: `array`):

Exact numeric SofaScore event IDs. When supplied, discovery mode and date are ignored.

## `eventUrls` (type: `array`):

Exact public sofascore.com match URLs containing #id:<event ID>.

## `includeStatistics` (type: `boolean`):

Fetch possession, shots, passes, and other statistics where SofaScore makes them available. Upcoming and some live events may have none.

## `status` (type: `string`):

Keep all, scheduled, live, or finished events.

## `team` (type: `string`):

Optional case-insensitive filter applied to both home and away team names.

## `tournament` (type: `string`):

Optional case-insensitive tournament or competition name filter.

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

Maximum number of matched event records to save and charge.

## Actor input object example

```json
{
  "mode": "date",
  "sport": "football",
  "date": "2026-08-11",
  "eventIds": [],
  "eventUrls": [],
  "includeStatistics": true,
  "status": "all",
  "maxItems": 10
}
```

# Actor output Schema

## `dataset` (type: `string`):

All matched SofaScore event records.

# 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 = {
    "mode": "date",
    "sport": "football",
    "date": "2026-08-11",
    "eventIds": [],
    "eventUrls": [],
    "includeStatistics": true,
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/sofascore-live-events-statistics-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 = {
    "mode": "date",
    "sport": "football",
    "date": "2026-08-11",
    "eventIds": [],
    "eventUrls": [],
    "includeStatistics": True,
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/sofascore-live-events-statistics-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 '{
  "mode": "date",
  "sport": "football",
  "date": "2026-08-11",
  "eventIds": [],
  "eventUrls": [],
  "includeStatistics": true,
  "maxItems": 10
}' |
apify call automation-lab/sofascore-live-events-statistics-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/sofascore-live-events-statistics-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/9D9fmPvSJklFASxeh/builds/te4Vdig0fBHgEn5L2/openapi.json