# ESPN Depth Chart Scraper - NFL, NBA, MLB Starters (`hgservices/espn-depth-chart-scraper`) Actor

Scrape ESPN depth charts for every NFL, NBA and MLB team. Get the starter and each backup at every position with player name, jersey and headshot. Filter by team, player, position or depth. Export JSON, CSV or Excel.

- **URL**: https://apify.com/hgservices/espn-depth-chart-scraper.md
- **Developed by:** [Harish Garg](https://apify.com/hgservices) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.00 / 1,000 depth chart rows

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## ESPN Depth Chart Scraper — NFL, NBA, MLB Starters and Backups

Get the current **ESPN depth chart** for every **NFL, NBA and MLB** team as clean, structured data. See the **starter and every backup at every position** — quarterback, running back, point guard, starting pitcher, closer and more — with each player's name, jersey number, position and headshot photo.

Filter by team, player, position or depth. Download the results as JSON, CSV or Excel, call the Actor from the API, or ask for a depth chart from an AI assistant such as Claude or ChatGPT. No ESPN account or API key needed.

### What does ESPN Depth Chart Scraper do?

It collects the depth chart of every team in the leagues you pick and returns one row per player per position. Each row tells you:

- **Who** — player name, ESPN player ID, jersey number, position and headshot photo
- **Where** — team, league, and the position on the chart (for example `QB`, `LT`, `PG`, `SP`, `CL`)
- **How deep** — depth rank: `1` is the starter, `2` the first backup, and so on
- **Which formation** — for the NFL, the formation or unit, for example `3WR 1TE`, `Base 4-3 D` or `Special Teams`

A one-team run finishes in a few seconds. A full league finishes in under a minute, and all three leagues in about one minute.

### Who is it for?

- **Fantasy football, basketball and baseball players** — find each team's starters before lineup lock, and see who moves up when a starter is hurt.
- **Sports bettors and betting model builders** — a starter change moves lines. Collect a daily snapshot and track depth chart changes over time.
- **Sports media, newsletters and apps** — feed a depth chart table, a website widget or a "starter change" alert.
- **Analysts and researchers** — compare how deep each team is at a position across a league.

### Supported leagues

| League | Code | Charts per team |
|--------|------|-----------------|
| NFL | `nfl` | Several — one per formation or unit, such as `3WR 1TE`, `Base 4-3 D` and `Special Teams` |
| NBA | `nba` | One, named `Depth Chart` |
| MLB | `mlb` | One, named `Depth Chart`, with starting pitchers, relievers and every fielding position |

ESPN does not publish current depth charts for the NHL, the WNBA, college sports or soccer, so those leagues are not offered.

### How to get an ESPN depth chart

1. Open the Actor and pick one or more **leagues**.
2. Optionally, enter **teams** (for example `KC`, `Lakers` or `New York Yankees`), or set **Maximum depth** to `1` for starters only.
3. Click **Start**.
4. Open the **Output** tab to see the table, or export the data as JSON, CSV, Excel, XML or HTML.

To keep your data current, create a **schedule** (for example every morning) and connect it to Google Sheets, Slack, a webhook or your database.

### Input

| Field | What it does | Example |
|-------|--------------|---------|
| **Leagues** | Leagues to get depth charts for | `["nfl"]`, `["nba", "mlb"]` |
| **Teams** | Team abbreviations or team names. Leave empty for every team | `["KC", "49ers"]`, `["Lakers"]` |
| **Maximum depth** | Only players this deep or higher. `1` = starters only, `2` = starters and first backups | `1` |
| **Players** | Part of a player's name | `["mahomes"]` |
| **Positions** | Position abbreviations or names. Matches the player's position or the chart position | `["QB", "RB"]`, `["Point Guard"]`, `["SP"]` |

Text filters ignore upper and lower case. A team abbreviation or city applies in every league you select: `KC` gives the Kansas City Chiefs in the NFL and the Kansas City Royals in MLB.

#### Example: one NFL team's full depth chart

```json
{
  "leagues": ["nfl"],
  "teams": ["KC"]
}
```

#### Example: every NFL starter

```json
{
  "leagues": ["nfl"],
  "maxDepthRank": 1
}
```

#### Example: starting and backup quarterbacks for every NFL team

```json
{
  "leagues": ["nfl"],
  "positions": ["QB"],
  "maxDepthRank": 2
}
```

#### Example: the Lakers' starting five

```json
{
  "leagues": ["nba"],
  "teams": ["Lakers"],
  "maxDepthRank": 1
}
```

#### Example: NBA point guards and MLB starting pitchers

```json
{
  "leagues": ["nba", "mlb"],
  "positions": ["PG", "SP"]
}
```

### Output

One row per player per position per chart. This is a real row from an NFL run:

```json
{
  "recordType": "depthChartEntry",
  "league": "nfl",
  "leagueName": "NFL",
  "sport": "football",
  "season": { "year": 2026, "displayName": "2026", "type": "Regular Season" },
  "team": { "id": "12", "name": "Kansas City Chiefs", "abbreviation": "KC" },
  "player": {
    "id": "4241385",
    "name": "Creed Humphrey",
    "shortName": "C. Humphrey",
    "jersey": "52",
    "position": "Center",
    "positionAbbreviation": "C",
    "headshot": "https://a.espncdn.com/i/headshots/nfl/players/full/4241385.png"
  },
  "depthChart": {
    "id": "21",
    "name": "3WR 1TE",
    "positionSlot": "c",
    "position": "Center",
    "positionAbbreviation": "C"
  },
  "rank": 1,
  "slot": null,
  "isStarter": true,
  "retrievedAt": "2026-09-22T13:51:19.187Z"
}
```

#### Output fields

| Field | Description |
|-------|-------------|
| `league`, `leagueName`, `sport` | League code (`nfl`), name (`NFL`) and sport |
| `season` | Season year, ESPN's season label (for example `2026-27` in the NBA) and phase (`Preseason`, `Regular Season`, `Postseason`) |
| `team` | Team ESPN ID, name and abbreviation |
| `player` | ESPN player ID, name, short name, jersey number, position and headshot URL |
| `depthChart.name` | The chart: an NFL formation or unit such as `3WR 1TE`, or `Depth Chart` in the NBA and MLB |
| `depthChart.position` | The position on the chart, for example `Quarterback` or `Starting Pitcher` |
| `rank` | Depth at the position: `1` is the starter, `2` the first backup |
| `isStarter` | `true` when `rank` is `1` |
| `slot` | The column, when a chart lists a position more than once: `1`, `2` and `3` are the three wide receiver spots in the NFL `3WR 1TE` formation. `null` for every other position |
| `retrievedAt` | When your run collected the data. The same for every row of a run, so daily snapshots are easy to compare |

Rows come sorted by league, team, chart, position and depth. Each run also saves a **run summary** (row counts, leagues and filters) in the key-value store under `SUMMARY`.

**Good to know:**

- An NFL player can appear more than once — once for each formation or unit they are listed in. Filter on `depthChart.name` to keep one formation.
- The NFL `3WR 1TE` formation has three starting wide receivers. Each has `rank: 1`, and `slot` tells them apart.
- In MLB, the `P` position lists the starting rotation in order: `rank: 1` is the first starter. Relievers are under `RP` and the closer under `CL`.

### How to use ESPN Depth Chart Scraper

#### In Apify Console

Fill in the input form and click **Start**. Save your setup as a **task** to run it again with one click, or add a **schedule** to run it every day.

#### With the Apify API

Run the Actor and get the results in one HTTP call. Replace `YOUR_API_TOKEN` with your token from **Settings → API & Integrations**.

```bash
curl -X POST "https://api.apify.com/v2/acts/hgservices~espn-depth-chart-scraper/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"leagues": ["nfl"], "teams": ["KC"], "maxDepthRank": 1}'
```

Add `&format=csv` to the URL to get CSV instead of JSON.

#### With JavaScript

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

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });
const run = await client.actor('hgservices/espn-depth-chart-scraper').call({
    leagues: ['nba'],
    maxDepthRank: 1,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### With Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")
run = client.actor("hgservices/espn-depth-chart-scraper").call(
    run_input={"leagues": ["nfl"], "positions": ["QB"], "maxDepthRank": 1}
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["team"]["abbreviation"], item["player"]["name"])
```

#### With Claude, ChatGPT and other AI assistants

Connect your AI assistant to the **Apify MCP server** at `https://mcp.apify.com`, then ask in plain language. The assistant runs this Actor for you and answers from the results.

- **Claude (claude.ai or Claude Desktop):** add a custom connector with the URL `https://mcp.apify.com`.
- **Claude Code:** run `claude mcp add --transport http apify https://mcp.apify.com`.
- **ChatGPT:** add `https://mcp.apify.com` as a connector (MCP server) in ChatGPT settings.
- **Cursor, VS Code, Windsurf and other MCP clients:** add `https://mcp.apify.com` as an MCP server.

Sign in with your Apify account when asked. Example prompts:

- *"Who is the backup running back for the 49ers? Use the ESPN Depth Chart Scraper."*
- *"List the starting quarterback of every NFL team."*
- *"Show me the Yankees' starting rotation and bullpen from ESPN."*
- *"Who starts at point guard for the Lakers?"*

#### With integrations

Send the results to **Google Sheets, Slack, Discord, email, Zapier, Make, n8n, Airbyte** or any **webhook**, from the Actor's **Integrations** tab. A common setup: run every morning, compare the starters with yesterday's run, and post the changes to a Slack channel.

### Scheduling ideas

| Use case | Cron (UTC) | When |
|----------|------------|------|
| Daily depth chart snapshot | `0 13 * * *` | Every day at 9 AM US Eastern |
| NFL midweek update | `0 12 * * 3` | Wednesday, when teams release weekly depth charts |
| NFL game-day starters | `0 15 * * 0` | Sunday 11 AM US Eastern, before the early kickoffs, with `maxDepthRank: 1` |

### FAQ

**How current is the data?**
Each run gets the depth charts as ESPN shows them at that moment. Run it again, or schedule it, for newer data.

**When did a depth chart last change?**
ESPN does not publish a change date for depth charts. Schedule the Actor and compare runs with `retrievedAt` to see when a starter changed.

**Why does the same NFL player appear several times?**
NFL teams publish one chart per formation or unit, for example `3WR 1TE`, `Base 4-3 D` and `Special Teams`. A player is listed once in each chart they appear in.

**Why is a player's name empty in a few rows?**
Rarely, ESPN lists a player on a depth chart who is not on the team's published roster. The row still has the ESPN player ID, so you can join it to other data.

**My team filter returns nothing. Why?**
Use the ESPN team abbreviation (for example `KC`, `SF`, `LAL` or `NYY`) or a word from the team name (for example `Chiefs`, `Lakers` or `Red Sox`). Check that you selected the team's league. The run log and status message name every team that matched nothing.

**Can I combine it with other sports data?**
Yes. See the related Actors below. They use the same league codes, team fields and player fields, so their data joins directly.

### Related Actors

- **[ESPN Injury Report Scraper](https://apify.com/hgservices/espn-injury-report-scraper)** — Out, Doubtful, Questionable, IR and IL players with ESPN's notes. Combine with depth charts to find the player who replaces an injured starter.
- **[ESPN Transactions Scraper](https://apify.com/hgservices/espn-transactions-scraper)** — signings, releases, trades and IL moves.
- **[ESPN Sports Scores & Schedules](https://apify.com/hgservices/apify-actor-espn)** — scores, schedules, venues and broadcasts for every game.
- **[ESPN Player Box Scores & Game Logs](https://apify.com/hgservices/apify-actor-espn-player-stats)** — every stat for every player in every game.

### Feedback

Missing a league, a field or a filter? Open an issue on the Actor's **Issues** tab. We read every request.

### Disclaimer

This Actor is not affiliated with, endorsed by or sponsored by ESPN. It collects publicly available depth chart information. Use the data in line with ESPN's terms and the laws that apply to you.

# Actor input Schema

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

The leagues to get depth charts for. A whole league takes under a minute.

## `teams` (type: `array`):

Only return these teams. Use the abbreviation (KC, LAL, NYY) or the team name (Kansas City Chiefs, Lakers, Red Sox). Not case-sensitive. Leave empty for every team. A one-team run takes a few seconds. An abbreviation that several leagues use (KC, NY) matches every league you selected.

## `maxDepthRank` (type: `integer`):

Only return players this deep or higher at each position. Set 1 for starters only, 2 for starters plus first backups. Leave empty for the full chart.

## `players` (type: `array`):

Only return these players. Part of a name is enough, for example 'mahomes'. Not case-sensitive.

## `positions` (type: `array`):

Only return these positions. Use the abbreviation (QB, WR, PG, SP, RP) or the name (Quarterback, Point Guard). Matches the player's own position or the depth chart position they fill. Not case-sensitive.

## Actor input object example

```json
{
  "leagues": [
    "nfl"
  ]
}
```

# Actor output Schema

## `depthCharts` (type: `string`):

One row per player per position slot, ranked from starter down

## `summary` (type: `string`):

Row counts, leagues, filters and any league ESPN did not answer for

# 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"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("hgservices/espn-depth-chart-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 = { "leagues": ["nfl"] }

# Run the Actor and wait for it to finish
run = client.actor("hgservices/espn-depth-chart-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 '{
  "leagues": [
    "nfl"
  ]
}' |
apify call hgservices/espn-depth-chart-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,hgservices/espn-depth-chart-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/9PDd5anWM8PacBMto/builds/mGWHXpOb73sMDdv4k/openapi.json