ESPN NFL Season-Aware Stats Scraper

What does this Actor do?

ESPN NFL Season-Aware Stats Scraper collects public ESPN NFL team standings, roster/player metadata, scoreboard events, and news. It uses bounded HTTPS requests to ESPN’s public CDN and public site API routes, normalizes the business fields, and records source-season provenance for every normal row.

The Actor does not log in, use credentials, use a proxy, request arbitrary URLs, bypass CAPTCHA, paywalls, geofences, rate limits, device checks, or WAFs, or invent missing values. A blocked or unreadable source is reported through operational logs and run-summary counts; it never becomes a dataset row.

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

Scope and use cases

Use this Actor for season-aware NFL team snapshots, public roster research, scoreboard and schedule collection, and ESPN NFL news discovery. A run can discover teams from the public standings feed or accept bounded public ESPN team slugs, abbreviations, or IDs.

Normal dataset rows are one of nfl-team, nfl-player, nfl-game, or nfl-news. Operational issue counts are in the run summary, and failure details stay in run logs; diagnostic rows are not written to the dataset.

Source targets and public-page boundaries

The Actor uses these public ESPN routes:

• NFL standings and team discovery
• Team metadata and rosters
• Scoreboard
• NFL news

These are public ESPN web/CDN feeds, not private endpoints. Requests are sequential, response-size limited to 8 MiB, timed out at 15 seconds, and retried only for bounded transient server or transport failures. The Actor stops at the configured record limit and never substitutes a guessed team, player, game, or article.

Input

Complete public input

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 30,
  "season": 2026,
  "requestDelayMs": 250,
  "includePlayers": true,
  "maxPlayersPerTeam": 12
}

Input fields

• teams is optional and accepts up to 32 public ESPN team slugs, abbreviations, or numeric IDs. An empty list discovers teams from the public standings feed.
• maxTeams accepts 1 through 32 selected teams and defaults to 8.
• maxItems accepts 1 through 500 source-backed dataset rows and defaults to 120. Operational diagnostics do not consume the result limit.
• season accepts 2000 through 2035 and defaults to the current NFL season.
• requestDelayMs accepts 0 through 5,000 milliseconds and defaults to 250.
• includePlayers defaults to true and controls public roster retrieval.
• maxPlayersPerTeam accepts 0 through 100 and defaults to 20.

Unknown fields, credentials, proxy settings, arbitrary URLs, and email/contact extraction are rejected.

Runnable input examples

Public smoke run

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 5,
  "season": 2026,
  "includePlayers": false,
  "requestDelayMs": 0
}

Team and roster run

{
  "teams": [
    "buf",
    "mia"
  ],
  "maxTeams": 2,
  "maxItems": 40,
  "season": 2025,
  "includePlayers": true,
  "maxPlayersPerTeam": 10
}

Standings discovery with no team filter

{
  "teams": [],
  "maxTeams": 4,
  "maxItems": 23,
  "season": 2026,
  "requestDelayMs": 0
}

Player-free bounded run

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 20,
  "season": 2026,
  "includePlayers": false,
  "maxPlayersPerTeam": 0,
  "requestDelayMs": 500
}

Local fixture QA

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 5,
  "season": 2026,
  "includePlayers": true,
  "maxPlayersPerTeam": 2
}

Fixture mode is deterministic local QA only and is not Cloud evidence.

Output contract

Normal team row

Every normal row contains sourceName, sourceKind, sourceUrl, league, season, requestedSeason, seasonLabel, seasonStartYear, and scrapedAt, plus type-specific public fields.

{
  "recordType": "nfl-team",
  "sourceName": "ESPN public NFL feeds",
  "sourceKind": "public-espn-cdn",
  "sourceUrl": "https://cdn.espn.com/core/nfl/standings?xhr=1&season=2026",
  "league": "nfl",
  "season": 2026,
  "requestedSeason": 2026,
  "seasonLabel": "2026 NFL season",
  "seasonStartYear": 2026,
  "teamId": "2",
  "teamName": "Buffalo Bills",
  "teamAbbreviation": "BUF",
  "teamSlug": "buf",
  "wins": 3,
  "losses": 0,
  "winPercent": 1,
  "scrapedAt": "2026-09-09T00:00:00.000Z"
}

Normal game row

{
  "recordType": "nfl-game",
  "sourceName": "ESPN public NFL feeds",
  "sourceKind": "public-espn-api",
  "sourceUrl": "https://site.api.espn.com/apis/site/v2/sports/football/nfl/scoreboard?limit=100&dates=2026",
  "league": "nfl",
  "season": 2025,
  "requestedSeason": 2026,
  "seasonLabel": "2025 NFL season",
  "seasonStartYear": 2025,
  "eventId": "401000001",
  "eventName": "Buffalo Bills at Fixture Team",
  "eventDate": "2026-01-04T18:00:00.000Z",
  "homeTeam": "Fixture Team",
  "awayTeam": "Buffalo Bills",
  "homeScore": 24,
  "awayScore": 27,
  "gameStatus": "Final",
  "completed": true,
  "scrapedAt": "2026-09-09T00:00:00.000Z"
}

Operational diagnostics

Source, parsing, dataset-write, and optional key-value-store failures are reported in logs and counted in diagnosticCount. The dataset contains only source-backed team, player, game, and news records. diagnosticItems is always zero.

Field semantics

• requestedSeason is the input season.
• season is the source-reported season. For games, this is ESPN event.season.year when present.
• seasonStartYear equals season.
• seasonLabel is normalized as season plus the text NFL season.
• Team fields cover identity and available standings values.
• Player fields cover public roster identity, team, position, jersey, physical values, status, and public profile media.
• Game fields cover event identity, date, season type, competitors, scores, status, venue, and broadcasts.
• News fields cover article identity, headline, description, publication time, image, and public article URL.
• Missing values are omitted. They are never replaced with zero, false, unknown, or a placeholder.

Run summary and source metadata

Normal summary

OUTPUT_SUMMARY, OUTPUT, and SOURCE_METADATA keep execution state and provenance outside normal business rows.

{
  "source": "ESPN public NFL feeds",
  "status": "SUCCEEDED",
  "runStatus": "SUCCEEDED",
  "dataStatus": "COMPLETE",
  "season": 2026,
  "requestedSeason": 2026,
  "seasonLabelPolicy": "seasonLabel is normalized as \"{season} NFL season\" using the source-reported season.",
  "seasonStartYearPolicy": "seasonStartYear equals the source-reported season.year, or requestedSeason when the source omits it.",
  "requestedItemCount": 5,
  "recordsStored": 5,
  "normalCount": 5,
  "diagnosticCount": 0,
  "diagnosticItems": 0,
  "duplicateCount": 0,
  "attemptedRequests": 4,
  "typeCounts": {
    "nfl-team": 1,
    "nfl-game": 1,
    "nfl-news": 3
  },
  "fixtureMode": false,
  "completedAt": "2026-09-09T00:00:08.000Z"
}

Partial, empty, and failed outcomes

Run status and runStatus are SUCCEEDED or FAILED. dataStatus is COMPLETE, PARTIAL, NO_RESULTS, or FAILED. A partial run remains SUCCEEDED when at least one source-backed row was saved; operational issues are counted separately and diagnosticItems stays zero. A clean empty result is SUCCEEDED with NO_RESULTS. A run with an actual failure and no saved row is FAILED.

{
  "source": "ESPN public NFL feeds",
  "status": "SUCCEEDED",
  "runStatus": "SUCCEEDED",
  "dataStatus": "PARTIAL",
  "season": 2026,
  "requestedSeason": 2026,
  "seasonLabelPolicy": "seasonLabel is normalized as \"{season} NFL season\" using the source-reported season.",
  "seasonStartYearPolicy": "seasonStartYear equals the source-reported season.year, or requestedSeason when the source omits it.",
  "requestedItemCount": 5,
  "recordsStored": 2,
  "normalCount": 2,
  "diagnosticCount": 1,
  "diagnosticItems": 0,
  "duplicateCount": 0,
  "attemptedRequests": 3,
  "typeCounts": {
    "nfl-team": 1,
    "nfl-player": 1
  },
  "fixtureMode": false,
  "completedAt": "2026-09-09T00:00:08.000Z"
}

For a clean empty feed, the summary reports status: "SUCCEEDED", dataStatus: "NO_RESULTS", recordsStored: 0, and diagnosticCount: 0.

{
  "source": "ESPN public NFL feeds",
  "status": "FAILED",
  "runStatus": "FAILED",
  "dataStatus": "FAILED",
  "season": 2026,
  "requestedSeason": 2026,
  "seasonLabelPolicy": "seasonLabel is normalized as \"{season} NFL season\" using the source-reported season.",
  "seasonStartYearPolicy": "seasonStartYear equals the source-reported season.year, or requestedSeason when the source omits it.",
  "requestedItemCount": 1,
  "recordsStored": 0,
  "normalCount": 0,
  "diagnosticCount": 1,
  "diagnosticItems": 0,
  "duplicateCount": 0,
  "attemptedRequests": 1,
  "typeCounts": {},
  "fixtureMode": false,
  "completedAt": "2026-09-09T00:00:08.000Z"
}

Source metadata

{
  "sourceName": "ESPN public NFL feeds",
  "sourceWebsite": "https://www.espn.com/nfl/",
  "directRequestsOnly": true,
  "fixtureMode": false,
  "seasonConvention": "ESPN NFL season.year is the season start year; a January or February game can belong to the prior season even when its calendar date is in the requested year.",
  "generatedAt": "2026-09-09T00:00:08.000Z"
}

How to scrape in Apify Console

Console steps

1. Open the Actor in Apify Console.
2. Select a season and optionally enter public ESPN team slugs or abbreviations.
3. Set maxItems and decide whether public roster players are needed.
4. Click Start and wait for the run to finish.
5. Review source-backed rows, run logs, OUTPUT_SUMMARY, and SOURCE_METADATA together.
6. Export the dataset in the format you need.

Public runs fetch ESPN data directly. Checked-in local fixtures are used only by the offline test suite and are not exposed as Actor inputs.

Cost and performance

Requests are sequential and paced by requestDelayMs. The run is bounded by maxTeams, maxItems, maxPlayersPerTeam, the 15-second per-request timeout, the 8 MiB response limit, and bounded retries. Lower maxItems and set includePlayers to false for a quick smoke check.

The Actor does not use a proxy or browser automation. Exact cost depends on Apify Actor compute, request latency, response size, and the number of selected teams and public roster records.

Advanced usage

Season-aware analysis

Use season for the requested feed year, then group games by the emitted season field. January and February games can belong to the prior NFL season even when their calendar date is in the next year.

Team selection

An empty teams array discovers teams from the public standings feed. A non-empty teams array requests only the listed public ESPN keys, bounded by maxTeams. Team records can be followed by roster, scoreboard, and news rows until maxItems source-backed rows are saved.

Fail-closed behavior

Access refusal, login prompts, CAPTCHA, paywalls, geofences, WAF checks, invalid JSON, oversized responses, and rate limits become operational diagnostics in logs and diagnosticCount; none are written to the dataset. The Actor never turns a blocked source into a zero-valued record.

API access

Apify API clients can start a run with the same JSON input, then read the default dataset and OUTPUT_SUMMARY, OUTPUT, and SOURCE_METADATA key-value records. This accesses Apify storage; it does not provide access to private ESPN systems.

{
  "teams": [
    "buf"
  ],
  "maxTeams": 1,
  "maxItems": 5,
  "season": 2026,
  "includePlayers": false
}

Do not place credentials, cookies, private headers, or signed storage URLs in support tickets or public examples.

Troubleshooting

The run contains no dataset records

Check the summary's dataStatus and diagnosticCount, then inspect the run logs for error codes and source URLs. Retry later for transient network or upstream errors; do not increase access or bypass settings because none are supported.

The season appears inconsistent

Compare requestedSeason, season, seasonStartYear, and seasonLabel. ESPN season.year is the NFL season start year, not always the calendar year of eventDate.

Fewer records than maxItems

maxItems is an upper bound on source-backed dataset rows. The public feed may contain fewer usable teams, players, games, or articles; diagnostics do not consume output slots.

Fixture data appears in a run

For live evidence, use the public ESPN request path; fixture provenance is recorded in SOURCE_METADATA.fixtureMode for local tests.

Issues and support

For support, include the Apify run ID, non-secret input shape, summary status, diagnostic error codes, and public source URL. Do not include cookies, private headers, credentials, or signed storage URLs.

Privacy and non-affiliation

This Actor is an independent third-party tool. It collects public information from ESPN’s public NFL feeds and does not claim affiliation with, sponsorship by, or endorsement from ESPN. Treat athlete names, profiles, and images as potentially personal data; use them only for a lawful, legitimate purpose and respect ESPN’s terms and applicable law.