> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# ESPN Scores API

> ESPN game scores and schedules with league, teams, start time and a link to each game. Pick the leagues to cover.

`POST /v1/data/espn/scores/run`

**Pricing:** $0.0035 per score ($3.50 per 1,000).

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**leagues** `string[]`

Leagues to get scores for, e.g. nba, nfl or epl (Premier League). One request reads them all. Defaults to NFL, NBA, MLB, NHL and Premier League.

41 allowed values, for example `nfl` (NFL), `college-football` (College Football (NCAAF)), `ufl` (UFL), `nba` (NBA), `wnba` (WNBA), `mens-college-basketball` (Men's College Basketball (NCAAM)), `womens-college-basketball` (Women's College Basketball (NCAAW)), `mlb` (MLB), `college-baseball` (College Baseball), `nhl` (NHL). Fetch the full list with `GET /v1/data/espn/scores?expand=options`.

**date** `date` (default: today)

Day to get scores for, e.g. 2026-10-31 (20261031 also works). Defaults to today.

**maxResults** `integer` (default: 100)

How many scores to return in total. Defaults to 100; use 0 for all.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/espn/scores/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "leagues": [
      "nba"
    ],
    "date": "2026-12-17",
    "maxResults": 10
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/espn/scores/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "leagues": [
        "nba"
    ],
    "date": "2026-12-17",
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/espn/scores/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "leagues": [
    "nba"
  ],
  "date": "2026-12-17",
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one score, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `gameId` | Game ID | text |
| `url` | URL | url |
| `league` | League | text |
| `leagueName` | League Name | text |
| `name` | Name | text |
| `shortName` | Short Name | text |
| `startTime` | Start Time | datetime |
| `status` | Status | object |
| `season` | Season | number |
| `seasonName` | Season Name | text |
| `week` | Week | number |
| `homeTeam` | Home Team | text |
| `homeTeamId` | Home Team ID | text |
| `homeAbbr` | Home Abbr | text |
| `homeScore` | Home Score | number |
| `homeRecord` | Home Record | text |
| `homeLogo` | Home Logo | image |
| `awayTeam` | Away Team | text |
| `awayTeamId` | Away Team ID | text |
| `awayAbbr` | Away Abbr | text |
| `awayScore` | Away Score | number |
| `awayRecord` | Away Record | text |
| `awayLogo` | Away Logo | image |
| `winner` | Winner | text |
| `venue` | Venue | object |
| `attendance` | Attendance | number |
| `neutralSite` | Neutral Site | boolean |
| `broadcasts` | Broadcasts | array |
| `odds` | Odds | object |
| `competitors` | Competitors | object\_array |
| `leaders` | Leaders | object\_array |
| `headline` | Headline | text |
| `headlineDescription` | Headline Description | text |
| `pageLinks` | Page Links | object |
| `notes` | Notes | array |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "espn/scores",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "headline": "Mobley scores 27, Allen adds 25 as Cavaliers ride 48-point second quarter to get past Bucks 136-111",
      "homeTeamId": "15",
      "homeRecord": "1-5",
      "awayTeamId": "5",
      "awayLogo": "https://a.espncdn.com/i/teamlogos/nba/500/scoreboard/cle.png",
      "season": 2027,
      "name": "Cleveland Cavaliers at Milwaukee Bucks",
      "headlineDescription": "— Evan Mobley scored 27 points and Jarrett Allen had 25 as the Cleveland Cavaliers cruised past the Milwaukee Bucks 136-111 on Saturday night.",
      "pageLinks": {
        "gamecast": "https://www.espn.com/nba/game/_/gameId/401909900/cavaliers-bucks",
        "boxscore": "https://www.espn.com/nba/boxscore/_/gameId/401909900",
        "highlights": "https://www.espn.com/nba/video?gameId=401909900",
        "playByPlay": "https://www.espn.com/nba/playbyplay/_/gameId/401909900",
        "recap": "https://www.espn.com/nba/recap?gameId=401909900",
        "teamStats": null
      },
      "homeTeam": "Milwaukee Bucks",
      "homeAbbr": "MIL",
      "awayScore": 136,
      "attendance": 12572,
      "awayAbbr": "CLE",
      "winner": "Cleveland Cavaliers",
      "competitors": [
        {
          "homeAway": "home",
          "id": "15",
          "abbreviation": "MIL",
          "displayName": "Milwaukee Bucks",
          "location": "Milwaukee",
          "nickname": "Bucks",
          "logo": "https://a.espncdn.com/i/teamlogos/nba/500/scoreboard/mil.png",
          "color": "00471b",
          "score": 111,
          "winner": false,
          "record": "1-5",
          "curatedRank": null,
          "linescores": [
            25,
            21,
            30
          ],
          "recordHome": "1-3",
          "recordRoad": "0-2",
          "form": null,
          "hits": null,
          "errors": null,
          "probable": null,
          "stats": {
            "rebounds": "45",
            "avgRebounds": "45.0",
            "assists": "33",
            "fieldGoalsAttempted": "100",
            "fieldGoalsMade": "41",
            "fieldGoalPct": "41.0",
            "freeThrowPct": "66.7",
            "freeThrowsAttempted": "18",
            "freeThrowsMade": "12",
            "points": "111",
            "threePointPct": "33.3",
            "threePointFieldGoalsAttempted": "51",
            "threePointFieldGoalsMade": "17",
            "avgPoints": "111.0",
            "avgAssists": "33.0",
            "threePointFieldGoalPct": "33.3"
          },
          "alternateColor": "eee1c6",
          "teamUrl": "https://www.espn.com/nba/team/_/name/mil/milwaukee-bucks"
        },
        {
          "homeAway": "away",
          "id": "5",
          "abbreviation": "CLE",
          "displayName": "Cleveland Cavaliers",
          "location": "Cleveland",
          "nickname": "Cavaliers",
          "logo": "https://a.espncdn.com/i/teamlogos/nba/500/scoreboard/cle.png",
          "color": "860038",
          "score": 136,
          "winner": true,
          "record": "4-2",
          "curatedRank": null,
          "linescores": [
            24,
            48,
            37
          ],
          "recordHome": "3-0",
          "recordRoad": "1-2",
          "form": null,
          "hits": null,
          "errors": null,
          "probable": null,
          "stats": {
            "rebounds": "56",
            "avgRebounds": "56.0",
            "assists": "41",
            "fieldGoalsAttempted": "100",
            "fieldGoalsMade": "52",
            "fieldGoalPct": "52.0",
            "freeThrowPct": "66.7",
            "freeThrowsAttempted": "18",
            "freeThrowsMade": "12",
            "points": "136",
            "threePointPct": "43.5",
            "threePointFieldGoalsAttempted": "46",
            "threePointFieldGoalsMade": "20",
            "avgPoints": "136.0",
            "avgAssists": "41.0",
            "threePointFieldGoalPct": "43.5"
          },
          "alternateColor": "bc945c",
          "teamUrl": "https://www.espn.com/nba/team/_/name/cle/cleveland-cavaliers"
        }
      ],
      "notes": null,
      "awayTeam": "Cleveland Cavaliers",
      "venue": {
        "name": "Fiserv Forum",
        "city": "Milwaukee",
        "state": "WI",
        "country": null,
        "indoor": true,
        "id": "5777"
      },
      "leaders": [
        {
          "team": "MIL",
          "category": "Points",
          "athlete": "Kel'el Ware",
          "value": "19"
        },
        {
          "team": "MIL",
          "category": "Rebounds",
          "athlete": "Kel'el Ware",
          "value": "10"
        }
      ],
      "url": "https://www.espn.com/nba/game/_/gameId/401909900/cavaliers-bucks",
      "league": "nba",
      "gameId": "401909900",
      "status": {
        "state": "post",
        "detail": "Final",
        "completed": true,
        "period": 4,
        "clock": "12:00",
        "name": "STATUS_FINAL",
        "shortDetail": "Final"
      },
      "seasonName": "regular-season"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.