ESPN Public Video URL Extractor

This Actor finds complete, unrestricted video records exposed by ESPN's public scoreboard and game-summary JSON. It returns the preferred public HTTPS MP4 or HLS URL plus useful game and video metadata. It does not copy media bytes, sign in, use private APIs, follow authentication redirects, or work around CAPTCHA, paywall, geographic, device, rate, WAF, or other access restrictions.

Input

• league: one of the supported ESPN league slugs, such as mlb, nba, or nfl.
• dates: optional YYYYMMDD date or chronological range of at most 31 days.
• eventIds: optional unique ESPN event IDs. This skips the scoreboard lookup.
• maxGames: 1–50 games to inspect.
• maxVideosPerGame: 1–20 source videos per game.
• maxItems: exact global output cap from 1–100.
• proxyConfiguration: standard Apify proxy configuration. The default is ordinary US residential access because ESPN can reject datacenter clients.

Input is strict: unknown fields, coercive numeric strings, invalid calendar dates, duplicate/invalid event IDs, contradictory proxy settings, and excessive limits fail before any public request.

Output

The dataset contains video records only. Every record has a stable video key, headline, preferred media URL and format, all detected media variants, complete game identity/date, league, public source endpoint/status, extraction method, proxy state, and scrape time. Optional descriptions, duration, page/thumbnail URLs, status, season, score, and team fields are omitted when ESPN does not expose them; they are never filled with null placeholders.

The Actor deduplicates globally by public video identity, preserves source order, skips restricted videos, and writes at most exactly maxItems. If the source is blocked, malformed, empty, or exposes no unrestricted public media URL, the dataset remains empty, a structured diagnostics record is stored in the default key-value store, and the run fails.

Request safety and resource bounds

Requests are sequential, paced by at least 350 ms, limited to 20 seconds and 3 MB each, and use at most two attempts. The second attempt is only for a transient network, timeout, or HTTP 5xx failure. Redirects and all access-control signals stop immediately without retries or alternate/private access paths. Output URLs must be public HTTPS targets; credentialed, local, private-network, and non-HTTPS URLs are discarded.

This Actor returns public URLs rather than downloading ESPN media files. Users are responsible for ESPN's terms, media rights, and applicable law when consuming a returned URL.

Local QA

npm ci
npm test
npm run check
npm audit --omit=dev
apify run --purge --input-file .actor/input.json

The unit suite uses a bounded synthetic fixture shaped like the public response structure. The supplied local live input disables proxy use so a host-level denial is recorded rather than hidden.