ESPN Scoreboard Monitor

ESPN Scoreboard Monitor is an Apify Actor that captures live and historical scoreboard states for NFL, NCAA college football, NBA, WNBA, and MLB. Each run pulls matchup metadata, score updates, and live situation context directly from ESPN scoreboards, normalizes the payloads, and emits deterministic JSON for datasets, webhooks, and long-term storage so you can automate alerts without hand-rolled scripts.

Because it runs on Apify you also inherit scheduling, monitoring, proxy rotation, and instant APIs for every dataset run.

🏈🏀 Key capabilities

• ⚡ Capture live scoreboard states and status changes on repeatable Apify schedules.
• 📅 Backfill historical scoreboards by single day or range and store each run in Apify datasets.
• 🧭 Track inning, possession, down-and-distance, last play, and other ESPN situation fields when available.
• 🔌 Trigger webhooks, Make/Zapier automations, or custom scripts the moment new events arrive.
• 🛡️ Keep runs stable with built-in proxy rotation, run notifications, and compute usage reports.

What data can ESPN Scoreboard Monitor extract?

Data point	Description	Example
league	ESPN league scraped during the run	mlb
target_date	Date the scoreboard snapshot represents	2024-07-04
event_id	ESPN event identifier for the matchup	401569780
matchup	Human-readable pairing shown on the scoreboard	NYM @ WSH
status.detail	Friendly game status pulled from ESPN	Final
home.score / away.score	Current or final team scores	1, 0
situation	Live context (inning, down, possession, last play, etc.)	{ "inning": "Bottom 8", "last_play": "Thomas stole 2nd." }
retrieved_at	UTC timestamp when the Actor fetched the scoreboard	2025-11-05T12:19:38.648039+00:00
source	ESPN API endpoint used for the snapshot	espn.apis.site.v2.scoreboard

🛠️ How to use ESPN Scoreboard Monitor to scrape ESPN data

1. Create a free Apify account or open the Actor detail page in Console.
2. Click Try for free and open the Input tab.
3. Select the league you need, choose optional state or date filters, and specify any webhook delivery settings.
4. Run locally with apify run --purge for a quick test, or schedule the Actor in Console for continuous coverage.
5. Review the Dataset tab, download JSON/CSV/Excel exports, or call the dataset REST API in your apps.

🧾 Input configuration

Apify Console exposes a form-based schema (see the Input tab) with these primary options:

• League sections (🏈 NFL, 🏀 NBA, 🏀 WNBA, ⚾ MLB, 🎓🏈 College Football) now sit side-by-side. Toggle each enabled switch to run one or many leagues in the same actor run.
• options.state: Focus on live, final, upcoming, or the smart auto mode that cascades through all three.
• options.date: Pin the scrape to a specific calendar day, or leave blank to track today's slate.
• options.date_start / options.date_end: Supply a range when you want to replay multiple days of results; ISO dates and relative lookbacks such as 3 days are both accepted.
• options.limit: Cap the maximum number of events per run (defaults to 50; omit it to keep the full scoreboard).
• College Football adds options.season, options.seasontype, options.week, and options.groups without cluttering other league sections.
• webhook: Optional HTTPS destination that receives the same payload stored in the dataset.

📤 Output example

You can download every run as JSON, CSV, Excel, or integrate via API clients like apify-client. A trimmed JSON sample looks like:

{
  "league": "mlb",
  "season": 2024,
  "target_date": "2024-07-04",
  "state_filter": "post",
  "event_id": "401569780",
  "matchup": "NYM @ WSH",
  "state": "post",
  "status": { "detail": "Final", "short": "Final" },
  "start_time": {
    "local": "2024-07-04T15:05:00+00:00",
    "utc": "2024-07-04T15:05:00+00:00"
  },
  "home": {
    "name": "Washington Nationals",
    "abbreviation": "WSH",
    "score": "1",
    "score_value": 1,
    "winner": true,
    "periods": [
      { "period": 1, "label": "Q1", "display_value": "0", "value": 0.0 },
      // ...
      { "period": 8, "label": "8", "display_value": "1", "value": 1.0 }
    ]
  },
  "away": {
    "name": "New York Mets",
    "abbreviation": "NYM",
    "score": "0",
    "score_value": 0,
    "winner": false,
    "periods": [
      { "period": 1, "label": "Q1", "display_value": "0", "value": 0.0 },
      // ...
      { "period": 9, "label": "9", "display_value": "0", "value": 0.0 }
    ]
  },
  "situation": {}, // Populated with live context when ESPN publishes it.
  "retrieved_at": "2025-11-05T12:19:38.648039+00:00",
  "source": "espn.apis.site.v2.scoreboard"
}

When the actor finishes, the default key-value store's OUTPUT document bundles a leagues array and an aggregated summary so multi-league runs stay traceable. Single-league runs still expose the legacy top-level keys (league, metadata, records, state) for backwards compatibility.

The output schema keeps field ordering consistent so diffing runs or streaming to warehouses stays clean.

💰 Pay-per-event pricing

Pricing is configured via Apify’s pay-per-event model; the table below mirrors the values we publish in Apify Console so users know exactly what each run costs.

Event	Default price	Description
league-run	$0.005	Charges once per league orchestration to cover lookups, normalization, and dataset preparation.
apify-default-dataset-item	$0.005	Apify's synthetic dataset event that charges each scoreboard record written to the default dataset and exposed via the dataset API.
webhook-delivery	$0.03	Optional fan-out fee collected when the aggregated payload is delivered to an external webhook URL.

apify-default-dataset-item is managed automatically by Apify when the run writes to the default dataset; we mirror its published price in our internal (maintainer-only) pay_per_event.json manifest so the local estimator and Console stay in sync.

Apify automatically enforces each user's maxTotalChargeUsd limit and exposes it inside the run as the ACTOR_MAX_TOTAL_CHARGE_USD environment variable. When a run runs out of budget, the actor stops enabling additional leagues and skips webhook delivery to keep costs predictable.

Feel free to tune the placeholder prices directly in Apify Console after pushing a new build—our internal JSON manifest tracks the published intent so downstream users (and Git history) can see why pricing changed.

To estimate costs locally before publishing, run the actor with apify run --max-total-charge-usd=<budget> and then execute python scripts/estimate_charges.py. The helper inspects storage/datasets/charging_log/ and combines the recorded event counts with the prices declared in the internal pay_per_event.json so you can iterate on pricing without leaving your workstation.

🔗 Related Actors and automations

• Pair with Apify's Dataset to Google Sheets or Notion Export Actors to sync scoreboards into dashboards automatically.
• Use Webhook Dispatcher or Make/Zapier integrations to fan out alerts when status changes to final.
• Combine with Apify's Email or Slack Notification templates to deliver score change alerts to stakeholders in real time.

❓FAQ, disclaimers, and support

Is it legal to scrape ESPN?

Web scraping is legal when you're collecting publicly available data, which covers the vast majority of ESPN scoreboard content. Still, you must respect boundaries such as personal data and intellectual property regulations, follow ESPN's Terms of Use (which reference the full Disney Terms of Use), and only process personal data when you have a legitimate basis to do so. If you're unsure, consult legal counsel and review Apify's primer on the legality of web scraping.

Do I need proxies or ESPN API keys?

The Actor relies on ESPN's public JSON endpoints so most runs succeed with Apify's shared datacenter proxies. Large-scale historical exports benefit from residential rotation—configure this directly in the Actor's Proxy section. No ESPN API key is required.

Can I automate historical backfills and live updates together?

Yes. Use Apify's scheduling to run a nightly historical job with tight date_range windows, then layer a separate high-frequency monitor (e.g., every 2 minutes) for live events. Each run writes to its own dataset, making it easy to merge or keep them isolated.

Your feedback

We’re always working to improve the Actor. If you’ve got technical feedback or found a bug, open an issue via the Actor’s Issues tab in Apify Console so we can triage it quickly.