# ESPN Scores API

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

**Pricing:** $0.0035 per score

**Endpoint:** `POST /v1/data/espn/scores/run`

**Auth:** `Authorization: Bearer mk_live_...`

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `leagues` | array | No | 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. |
| `date` | date | No | Day to get scores for, e.g. 2026-10-31 (20261031 also works). Defaults to today. |
| `maxResults` | integer | No | How many scores to return in total. Defaults to 100; use 0 for all. |

## Example

`?wait=true` holds the request open until the run finishes (up to 60s) and returns the rows inline: one request, no polling.

```bash
curl -X POST "https://api.mindcase.co/v1/data/espn/scores/run?wait=true" \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params":{}}'
```

```python
import requests

resp = requests.post(
    "https://api.mindcase.co/v1/data/espn/scores/run",
    params={"wait": "true"},
    headers={"Authorization": "Bearer mk_live_YOUR_API_KEY"},
    json={"params": {}},
)
rows = resp.json()["data"]
```

## Longer runs

If the run is still going at the 60s ceiling you get back `{ job_id, status: "running" }` instead of rows (same if the result is over 100 rows; those come back `truncated`). Poll with that `job_id`:

```bash
# 1) check status
curl https://api.mindcase.co/v1/jobs/JOB_ID \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"

# 2) when status == completed, fetch the rows
curl https://api.mindcase.co/v1/jobs/JOB_ID/results \
  -H "Authorization: Bearer mk_live_YOUR_API_KEY"
```

Full API reference (auth, jobs, balance, SDKs, MCP): https://mindcase.co/skills.md

## Response columns

| Field | Display 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 |