# Build a daily NBA archive.

> Backfill NBA points, rebounds and assists, then maintain a daily archive of observed Underdog lines and grades with cursor pagination and correction-safe upserts. Underdog API (https://underdogapi.com) is an independent Underdog Fantasy pick'em data API: Higher/Lower lines with separate payout multipliers per side, line history, changes and graded results as JSON, CSV, MCP and streams.

Canonical page: https://underdogapi.com/docs/daily-archive

## Free offer

**Free API key, no card: 100 credits a month** on the live board, every league, separate Higher/Lower prices, and the last 24 hours of line history. Sign up: https://underdogapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Get a free key at https://underdogapi.com/sign-up?ref=ai-claudebot (no card), or let your agent request one: `POST https://underdogapi.com/api/v1/agent/signup` with `data_wanted` and `use_case`, then show your user the returned approval_url.
2. Export it: `export UNDERDOG_API_KEY=ud_...`
3. First call with curl:

```bash
curl --fail-with-body 'https://underdogapi.com/api/v1/projections?league=NBA&view=compact&limit=5' \
  -H "Authorization: Bearer $UNDERDOG_API_KEY" \
  -H 'X-User-Request: NBA dashboard integration check'
```

4. Same call in Python:

```python
import os, requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"league": "NBA", "view": "compact", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
)
r.raise_for_status()
for line in r.json()["data"]:
    print(line["player"]["name"], line["market"]["stat"], line["line"])
```

## Use it from Claude (MCP)

Claude Code, one command:

```bash
claude mcp add --transport http underdog https://underdogapi.com/api/mcp --header "Authorization: Bearer $UNDERDOG_API_KEY"
```

Or add this server to your Claude MCP configuration (the key stays in the environment):

```json
{
  "mcpServers": {
    "underdog": {
      "type": "http",
      "url": "https://underdogapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${UNDERDOG_API_KEY}"
      }
    }
  }
}
```

Guide: https://underdogapi.com/use-with-claude

## Pricing

| Plan | Price | Credits / month | Notes |
| --- | --- | --- | --- |
| Free | $0 | 100 | No card. Live feed 5 minutes behind; last 24 hours of line history |
| Developer | $49/month | 10,000 | For models that need full training pages and loaded game-log seasons. Live feed, no added plan delay |
| Production | $149/month | 50,000 | For apps with real users and push delivery. Everything in Developer, signed webhooks for every change |
| Scale | $499/month | 250,000 | For apps whose traffic has outgrown Production. Everything in Production, 15 live-feed connections at once |

Full pricing: https://underdogapi.com/pricing

## On this page

Backfill player points, rebounds and assists. Archive observed Underdog closing lines and their grades separately, then revisit recent dates as results settle.

[Download Python archive client](https://underdogapi.com/examples/daily-nba-archive.py)

## Choose the history you need

| Archive | Request | Stored data |
| --- | --- | --- |
| NBA player game logs | `/api/v1/game-logs?league=NBA&date=2023-10-24&limit=200` | One player per game; stats.points, stats.rebounds, stats.assists |
| Underdog results | `/api/v1/results?league=NBA&date=2026-11-02&stat=Points&limit=200` | Observed closing line, outcome, grading status and revision |

Database check on November 3, 2026: NBA player game logs span October 24, 2023–November 2, 2026 (110,025 stored player-game rows). NBA Underdog result records span October 28–November 2, 2026. These are observed range bounds, not a claim that every game or market is present. A separate partial first-party snapshot of 221 NBA lines has been recovered from October 27 at 22:55:20 UTC and is available through historical board and per-projection history reads. This does not establish October 27 grading coverage or a complete earlier season. Older box scores do not supply older Underdog lines. Check response coverage metadata and [coverage](https://underdogapi.com/docs#coverage) for current availability.

League-wide historical game logs and the full available historical dataset require Developer, Production or Scale access. Free samples and plan-limited results cannot validate a complete archive. The client stops on an access gate or plan-limit marker; it never works around an allowance.

## Run bounded backfills and daily updates

```
export UNDERDOG_API_KEY='your saved key'
# Download the Python client using the link above; Python 3.10+, no dependencies.
# One historical box-score day. Repeat in explicit windows of at most 31 days.
python3 daily-nba-archive.py --dataset game-logs --start 2023-10-24 --end 2023-10-24
# One observed Underdog day; Points, Rebounds and Assists, every grading status.
python3 daily-nba-archive.py --dataset results --start 2026-11-02 --end 2026-11-02
# Daily maintenance: re-read the previous five Eastern game dates.
python3 daily-nba-archive.py --db nba-archive.sqlite
# Optional: all available NBA markets instead of just PTS/REB/AST.
python3 daily-nba-archive.py --dataset results --all-markets --start 2026-11-02 --end 2026-11-02
```

Run from your own server or computer with a saved API key. The default makes at most 100 HTTP requests, including retries, at one request at a time. Narrow the date range if the budget is reached. A slice is saved only after all its pages arrive; completed slices remain saved, and rerunning safely updates their rows. The script does not create an unattended service for you.

1. Schedule one daily run after the prior day’s games, with no overlapping runs against the same SQLite file. Defaults use yesterday and the four preceding dates in `America/New_York`, including daylight-saving changes.
2. Follow `meta.next_cursor` with every filter unchanged. Game logs are newest first; result sequence cursors increase. Neither is a change feed or a frozen snapshot. Restart each date at page one on the next run, so a corrected older sequence is not missed.
3. The SQLite file keeps complete API rows. Game logs upsert by game and player ID; result records upsert by projection ID. Revisions, source times, confidence, grading reasons and side information stay in the saved JSON.
4. Read the `nba_points_rebounds_assists` SQL view for stats, and `graded_underdog` for records whose latest status is graded. The underlying result archive also keeps void and ungraded records. Never turn either status into a loss or a zero.
5. Missing stat fields remain SQL NULL, including rebounds or assists that the source did not report. A true recorded zero remains zero.
6. Keep a periodic deeper date replay for late corrections. Five days covers the usual box-score confirmation re-read, approximately four days after a game; it is not a promise that every future revision arrives within five days. Track ungraded and unconfirmed rows separately.

## Game date, observation time and capture time

`date` selects the US Eastern game date, not the date your script downloaded the row. A game ending after midnight UTC still belongs to its Eastern game date. `starts_at` is the event timestamp. For results, `closing.observed_at` is the last line observation before the start, and `closing.gap_seconds` reports its distance from that start. It is not proof of the final platform line immediately before lock.

The client adds `captured_at`, the UTC download time, without overwriting source timestamps. `graded_at`, `updated_at` and `revision` describe grading and corrections. The `archive_reads` table records finished API traversals, including empty slices; finishing pagination does not prove source completeness or final grading.

For flat training rows use [training-set](https://underdogapi.com/docs#training-set); it excludes void rows by default and uses `from/to` for date ranges. Game logs use `start_date/end_date`. Results use a single `date` per traversal. This client uses daily results without a status filter to preserve later status changes.

Every request sends the fixed task summary “Maintain a daily NBA points rebounds assists and observed graded-line archive.” It includes no private prompt or personal information. Keep keys in your environment and archives on storage you control.

[Open the model-training workspace](https://underdogapi.com/dashboard/playground?workflow=model-training) · [Check credit costs](https://underdogapi.com/credits)

## FAQ

### Is there a free Underdog API?

Yes. The Free plan is a real API key on the live board, not a sample: 100 credits a month, every league, separate Higher/Lower prices and the last 24 hours of line history. No card is needed.

### Is this the official Underdog Fantasy API?

No. Underdog API is an independent data service. It is not affiliated with, endorsed by or sponsored by Underdog Fantasy or Underdog Sports.

### What data does it return?

Underdog Higher/Lower lines with separate payout multipliers and availability for each side, stable market ids through line moves, alternate rungs, recorded line history, changes, graded results and coverage/status endpoints.

### How do I use it from Claude or another AI agent?

Connect the MCP server at https://underdogapi.com/api/mcp with a bearer key, or call the REST API. Agents can request a key for their user with POST /api/v1/agent/signup.

### How much does it cost after the free tier?

Developer is $49/month for 10,000 credits, Production $149/month for 50,000, Scale $499/month for 250,000. Errors and unchanged 304 responses cost zero credits.

### How fresh is the data?

Each row carries its observation time. Check /api/v1/status and /api/v1/coverage before relying on a sport or window; missing collection is reported as unavailable, never filled in.

### Does it place entries or give picks?

No. It is data only: no entries, account operations, guaranteed outcomes or betting advice.

---
Independent data service, not affiliated with Underdog Fantasy or Underdog Sports. Docs: https://underdogapi.com/docs · OpenAPI: https://underdogapi.com/openapi.json · llms.txt: https://underdogapi.com/llms.txt
