# Sports Scores & Schedules API (`lergassy/sports-scores-api`) Actor

Live scores, schedules, results, standings, teams, rosters, box scores and betting lines for 33 leagues — NFL, NBA, MLB, NHL, Premier League, LaLiga, Champions League, MLS, ATP, WTA, UFC, F1, PGA — from ESPN's public data. One flat row per game. No API key, no proxy.

- **URL**: https://apify.com/lergassy/sports-scores-api.md
- **Developed by:** [Matvey](https://apify.com/lergassy) (community)
- **Categories:** Sports, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.80 / 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

**Sports Scores & Schedules API** returns live scores, upcoming schedules, final results, standings, teams, rosters, box scores and betting lines for 33 leagues — NFL, NBA, MLB, NHL, college football and basketball, the Premier League, LaLiga, Bundesliga, Serie A, Champions League, MLS, ATP and WTA tennis, UFC, Formula 1, NASCAR and the PGA Tour — read from ESPN's public data. One flat row per game with status, start time, both teams, scores, records, venue, TV broadcast, the DraftKings line and a one-sentence summary you can drop straight into a message or a prompt. No API key, no proxy, no browser: a full day of games across three leagues takes about two seconds.

![One run of Sports Scores & Schedules API: NFL week one with season, status, score and venue.](https://raw.githubusercontent.com/lergassy/apify-actor-assets/main/sports-scores-api/sports-scores-api-output-table.png)

Pick the leagues and a date or a range of days, choose what you need — scores and schedule, standings, teams, a team's roster or season, game details or news — and click Start. Export as JSON, CSV or Excel, run it on a schedule, or call it from the API and AI agents.

### What is Sports Scores & Schedules API?

It is a **sports data API** for people who need scores and fixtures as a table rather than a web page: fantasy and betting tools, Discord and Telegram bots, dashboards, newsletters, research, and AI agents that get asked "who won last night" or "when do the Lakers play next". ESPN has no public API of its own and the licensed feeds cost hundreds of dollars a month; this Actor reads the same data ESPN's site uses, for a fraction of a cent per game.

### What data does it return?

#### Games — scores and schedule

| Field | Example |
|---|---|
| `league`, `leagueName`, `sport`, `season`, `week` | nfl · National Football League · football · 2026 · 1 |
| `eventId`, `name`, `shortName`, `startTime` | 401772510 · Seattle Seahawks at San Francisco 49ers · SEA @ SF · 2026-09-10T00:20Z |
| `status`, `statusDetail`, `period`, `clock`, `completed` | live · 3rd Quarter · 3 · 8:41 · false |
| `homeTeam`, `homeTeamId`, `homeScore`, `homeRecord`, `homeLogo`, `homeRank` | San Francisco 49ers · 25 · 17 · 2-0 · … · null |
| `awayTeam`, `awayScore`, `awayRecord`, `awayLinescores` | Seattle Seahawks · 10 · 1-1 · \[0, 7, 3] |
| `winner`, `participants` | San Francisco 49ers · (tennis and UFC: the two players or fighters) |
| `tournament`, `round` | US Open · Men's Singles — Round 2 (tennis, UFC cards) |
| `venue`, `city`, `attendance`, `neutralSite`, `broadcasts` | Lumen Field · Seattle · 68,742 · false · \["NBC"] |
| `oddsProvider`, `spread`, `overUnder`, `homeMoneyline`, `awayMoneyline`, `favorite` | DraftKings · SF -3.5 · 44.5 · -180 · +150 · home |
| `summary` | "Seattle Seahawks 10 – 17 San Francisco 49ers, 3rd Quarter" |
| `link` | ESPN game page |

#### Standings

`group` (conference / division / table), `rank`, `team`, `wins`, `losses`, `ties`, `otLosses`, `winPercent`, `points`, `gamesPlayed`, `pointsFor`, `pointsAgainst`, `pointDifferential`, `streak`, `gamesBehind`, `record`, `homeRecord`, `awayRecord`, plus every raw statistic ESPN publishes in `stats`.

#### Teams and players

Teams: `teamId`, `team`, `abbreviation`, `location`, `nickname`, `color`, `logo`, `link`. Players (roster mode): `player`, `jersey`, `position`, `age`, `height`, `weight`, `birthPlace`, `experience`, `college`, `status`, `headshot`.

#### Game details

`teamStats` (first downs, total yards, possession… per team), `leaders` (top passer, rusher, scorer with their line), `injuries`, `scoringPlays` with the running score, `winProbabilityHome`, `attendance`, `weather`, `officials`, and the closing `spread` and `overUnder`.

#### News

`headline`, `description`, `published`, `byline`, `link`, `image`, `categories` — the latest articles for each league.

### How much does it cost?

Pricing is **pay per row**: a game, a standings entry, a team, a player, a game detail or an article. There is no browser and no proxy in this Actor, so platform usage is close to zero — a league's whole day is one request. See the **Pricing** tab for the current rate.

### How to get sports scores and schedules

1. Choose **🏟️ Leagues** — one or several. Through the API you can also pass any ESPN soccer slug such as `eng.2` or a full path such as `soccer/ned.1`.
2. Leave the dates empty for today, or set **From** and **To** (up to 60 days), or use **Days ahead** for "the coming week".
3. Keep **What to get** on *Scores & schedule*, or switch to standings, teams, roster, team schedule, game details or news.
4. Optionally filter to upcoming, live or finished games, and switch on **Add game details** for box scores and leaders.
5. Click **Start** and export, or read the dataset through the API.

### ⬇️ Input

```json
{
  "leagues": ["nfl", "nba", "epl"],
  "mode": "scoreboard",
  "days": 7,
  "onlyStatus": "all"
}
```

#### Standings for several leagues

```json
{ "leagues": ["epl", "laliga", "bundesliga"], "mode": "standings" }
```

#### A team's roster and season

```json
{ "leagues": ["nba"], "mode": "roster", "teamIds": ["13"] }
```

Run the *teams* mode once to see every team's id.

#### Box score for specific games

```json
{ "leagues": ["nfl"], "mode": "game", "eventIds": ["401772510"] }
```

### ⬆️ Output

```json
{
  "type": "game",
  "sport": "football",
  "league": "nfl",
  "leagueName": "National Football League",
  "season": 2026,
  "week": 1,
  "eventId": "401772510",
  "name": "Seattle Seahawks at San Francisco 49ers",
  "shortName": "SEA @ SF",
  "startTime": "2026-09-10T00:20Z",
  "status": "scheduled",
  "statusDetail": "Wed, September 9th at 8:20 PM EDT",
  "homeTeam": "San Francisco 49ers",
  "homeTeamId": "25",
  "homeScore": 0,
  "homeRecord": "0-0",
  "awayTeam": "Seattle Seahawks",
  "awayTeamId": "26",
  "awayScore": 0,
  "awayRecord": "0-0",
  "venue": "Lumen Field",
  "broadcasts": ["NBC"],
  "oddsProvider": "DraftKings",
  "spread": "SF -2.5",
  "overUnder": 44.5,
  "summary": "Seattle Seahawks at San Francisco 49ers, Wed, September 9th at 8:20 PM EDT",
  "link": "https://www.espn.com/nfl/game/_/gameId/401772510",
  "scrapedAt": "2026-09-04T03:00:00.000Z"
}
```

Tennis returns one row per match with `participants`, `tournament` and `round`; UFC one row per bout; Formula 1 and golf one row per session or tournament. A league that cannot be read arrives as a `type: "error"` row with the URL and the reason, never as a silently missing day.

### Use cases

#### Bots and alerts

A Discord, Slack or Telegram bot that answers "scores?" with the `summary` field, or a schedule that pings the channel an hour before kick-off.

#### Fantasy and betting tools

Schedules, results, injuries and the closing line in one table, refreshed on a schedule.

#### Dashboards and newsletters

Standings and last night's results for every league you follow, exported to a sheet or a database every morning.

#### Research

A season of results with attendance, venue and scoring plays, without writing a scraper.

#### AI agents

An agent asked "when does Arsenal play next" or "did the Yankees win" calls the Actor with the league and a date range and reads the `summary` field back.

### Integrations and sports scores API

Run it from the [Apify API](https://docs.apify.com/api/v2), the JavaScript and Python clients, a schedule, or a webhook, and push results to Google Sheets, Slack, Discord or a database through **n8n**, **Make** or **Zapier**.

### 🤖 For AI Agents & LLM Apps

Compact reference for agents calling this Actor through the [Apify MCP server](https://mcp.apify.com) or the Apify API (`lergassy/sports-scores-api`).

**Purpose:** answers questions about games — who plays, when, where, the score and the line — plus standings, teams, rosters and news, for 33 leagues across American football, basketball, baseball, hockey, soccer, tennis, MMA, motorsport and golf. Use it for "what games are on tonight", "did X win", "show me the Premier League table", "when is the next Lakers game".

**Minimal input:**

```json
{ "leagues": ["nba"], "mode": "scoreboard", "days": 3 }
```

**Output:** one flat row per game — `league`, `leagueName`, `sport`, `season`, `week`, `eventId`, `name`, `shortName`, `startTime`, `status`, `statusDetail`, `period`, `clock`, `homeTeam`, `homeTeamId`, `homeScore`, `homeRecord`, `awayTeam`, `awayTeamId`, `awayScore`, `awayRecord`, `winner`, `venue`, `broadcasts`, `oddsProvider`, `spread`, `overUnder`, `homeMoneyline`, `awayMoneyline`, `summary`, `link`. Standings rows carry `rank`, `team`, `wins`, `losses`, `winPercent`, `points`, `streak`; team rows `teamId`; player rows `player`, `position`; news rows `headline`, `link`. Everything is flat except `homeLinescores`, `awayLinescores`, `broadcasts`, `participants` and the detail-mode arrays.

**Behaviors an agent should know:**

- `status` is `scheduled`, `live` or `final`; `statusDetail` is the human phrase ("Final", "3rd Quarter", "Sat, September 5th at 12:00 PM EDT"). Quote `summary` when a user wants one line.
- Dates: `dateFrom`/`dateTo` (YYYY-MM-DD) or `days` ahead from today. Default is today only. ESPN days run on US Eastern time — a game at 00:20Z on the 10th belongs to the 9th on ESPN.
- League keys are lower-case (`nfl`, `epl`, `ucl`, `atp`). Team ids and event ids come from this Actor's own rows; do not invent them.
- Scores are numbers, records are strings ("2-0", "1-0-1" for soccer W-D-L); `winner` is empty until the game is final.
- Betting lines are the pre-game DraftKings line ESPN shows; they are missing for leagues and games without a market.
- Tennis rows are matches (two `participants`, `round`, `tournament`); UFC rows are bouts; F1 and golf rows are sessions or tournaments without scores.
- `includeGameDetails` adds one request per game; leave it off for schedules. Roster and team-schedule modes need `teamIds`; game mode needs `eventIds`.
- No proxy is used and none is needed; a league that fails returns an `error` row.

### ❓ FAQ

#### Is it legal to use ESPN data?

The Actor reads the public JSON that ESPN's own website loads, without logging in or bypassing any control. Scores, schedules and standings are facts; how you use them is subject to your local law and ESPN's terms — check before commercial redistribution at scale.

#### Does it return live, in-play scores?

Yes. Run it while games are on and `status` is `live` with `period`, `clock` and the current score. Schedule it every few minutes for a live board.

#### Which leagues are supported?

33 by key, listed in the input. Any other ESPN soccer competition works by its slug (`eng.2`, `por.1`, `conmebol.libertadores`). Cricket and rugby are not on ESPN's US data feed.

#### How far back can I go?

As far as ESPN keeps scoreboards — years for the big leagues. Use `dateFrom`/`dateTo` in chunks of up to 60 days.

#### Can I use it with the Apify API or an MCP server?

Yes. It runs from the API and the official clients, and AI agents reach it through the Apify MCP server without extra setup.

#### Why is a game missing?

Postponed and cancelled games disappear from ESPN's scoreboard for that day. Check `statusDetail` on the days around it.

### Your feedback

Found a league that mis-parses or a field that is empty when it should not be? Open an issue on the **Issues** tab — every one gets answered.

### You might also like

| Actor | What it does |
|---|---|
| [Google Flights Scraper](https://apify.com/lergassy/google-flights-scraper) | Live flight prices, layovers and booking options |
| [Trip.com Scraper](https://apify.com/lergassy/tripcom-scraper) | Hotel prices and availability for a city and dates |
| [Airbnb Scraper](https://apify.com/lergassy/airbnb-scraper) | Airbnb listings for any place and dates |
| [Email Verifier & Phone Number Validator](https://apify.com/lergassy/email-phone-verifier) | Checks e-mails and phone numbers in bulk |

# Actor input Schema

## `leagues` (type: `array`):

Pick one or many. Through the API you can also pass any ESPN soccer slug such as <code>eng.2</code> or a full path such as <code>soccer/ned.1</code>.

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

Scores & schedule is the main one: one row per game with status, score, records, venue, broadcast and betting line.

## `dateFrom` (type: `string`):

First day of games to return, YYYY-MM-DD. Leave empty for today.

## `dateTo` (type: `string`):

Last day, YYYY-MM-DD. Up to 60 days per run.

## `days` (type: `integer`):

Shortcut instead of a to-date: 0 = today only, 7 = the coming week.

## `onlyStatus` (type: `string`):

Filter scoreboard rows by status.

## `includeGameDetails` (type: `boolean`):

Opens each game's summary: team stats, leaders, injuries, scoring plays, win probability and the betting line. One extra request per game.

## `teamIds` (type: `array`):

ESPN team ids for the roster and team-schedule modes. Run the teams mode once to see them.

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

ESPN event ids for the game-details mode — the eventId field of scoreboard rows.

## `newsLimit` (type: `integer`):

How many latest articles to return per league in the news mode.

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

Safety cap on rows written per run, across all leagues and modes.

## `concurrency` (type: `integer`):

How many ESPN requests to run at once. Six is fast and polite.

## Actor input object example

```json
{
  "leagues": [
    "nfl",
    "nba",
    "epl"
  ],
  "mode": "scoreboard",
  "days": 0,
  "onlyStatus": "all",
  "includeGameDetails": false,
  "newsLimit": 20,
  "maxItems": 1000,
  "concurrency": 6
}
```

# Actor output Schema

## `rows` (type: `string`):

One flat row per game (status, start time, home and away team with score and record, venue, broadcast, betting line, one-sentence summary), or per standings entry, team, player, game detail or news article depending on the mode.

# 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 = {
    "leagues": [
        "nfl",
        "nba",
        "epl"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("lergassy/sports-scores-api").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 = { "leagues": [
        "nfl",
        "nba",
        "epl",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("lergassy/sports-scores-api").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 '{
  "leagues": [
    "nfl",
    "nba",
    "epl"
  ]
}' |
apify call lergassy/sports-scores-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lergassy/sports-scores-api"
        }
    }
}

```

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/BcgiTgvdRwaSf2fWQ/builds/OlagIid2IshYaezl8/openapi.json