# Build a measured NBA research workflow

> Use recorded close-time data with clear limits. Begin with coverage, inspect a sample, choose a chronological split and compare a simple baseline. Report s 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/build-an-nba-prop-model

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

For developers who need to build a measured nba research workflow.

Use recorded close-time data with clear limits.

[Get free API key](https://underdogapi.com/sign-up) [API reference](https://underdogapi.com/docs)

## Not for

Entry placement or fantasy-account support

This independent data service does not operate a fantasy account.

Guaranteed outcomes

Observations support research; they do not predict a winning entry.

## Base rates to beat, NHL graded lines

Graded lines **4,740**

Standard Higher rate **52.7%**

Discounted Higher rate **56.1%**

Boosted Higher rate **28.3%**

| Market | Standard Higher rate | Standard rows | All tier rows |
| --- | --- | --- | --- |
| points | 40.0% | 85 | 926 |
| assists | 61.2% | 49 | 890 |
| goals | 50.0% | 2 | 882 |
| plus_minus | 63.0% | 27 | 578 |
| power_play_points | 80.0% | 5 | 520 |
| shots | 58.5% | 82 | 446 |
| blocked_shots | 48.9% | 45 | 193 |
| faceoffs_won | 55.1% | 49 | 135 |

Games from 2026-11-06 to 2026-11-13. Voids excluded. A short sample, so expect these to move. [Every market and player](https://underdogapi.com/hit-rates)

## NBA game logs, loaded

| Player | Opponent | Minutes |
| --- | --- | --- |
| Cooper Flagg | @ CLE | 38 |
| Jaden McDaniels | vs CHI | 37 |
| Kyrie Irving | @ CLE | 37 |
| Jonathan Kuminga | vs CHI | 35 |
| Mario Hezonja | vs DAL | 34 |
| Meleek Thomas | vs DAL | 34 |

32,187 NBA games loaded, through Nov 14, 00:00 UTC. [Game logs endpoint](https://underdogapi.com/docs#game-logs)

## 1. Choose one prediction target

Start with one player’s full-game NBA points in regular-season games. The target is the final points total, not whether a historical Underdog Fantasy line went over. That distinction lets you learn from loaded game-log seasons even when those games predate our observed Underdog Fantasy lines. The line archive starts on the first recorded observation; older box scores do not create older offered lines.

The first model is deliberately transparent: predict the mean points from the last five earlier games in the same season. Compare it with a second baseline, the mean of all earlier games in that season. There are no hand-picked matchup multipliers or claims that five games is the optimal window.

## 2. Import real regular-season game logs

Create a Free API key, save it as UNDERDOG_API_KEY in your environment, then download the Python script linked above. It uses Python 3’s standard library, so no packages need installing. The /game-logs request specifies league=NBA, player, season_type=regular and limit=200. A season filter is optional. Read meta.stats_leagues and returned warnings to confirm coverage; a player with no loaded games may return an empty page.

```
python3 nba-player-prop-model.py --player "Jayson Tatum"
# With a paid key and an available historical season:
python3 nba-player-prop-model.py --player "Jayson Tatum" --season 2025-26
```

The script follows meta.next_cursor while the response permits it and keeps every page’s metadata. If the API reports a plan limit, it keeps the returned sample and stops paging. Free’s ten-game limit can still produce a useful file and a few worked predictions; it is not a full-season evaluation. HTTP errors are left visible rather than being replaced with invented rows. For an unambiguous identity, use --player-id with the pl_ identifier from /players or a sp_ stats_player_id from game logs; the script sends player_id instead of player.

## 3. Clean points without turning missing values into zeros

The full game-log response places points under stats.points, the game key under stats_event_id, and the date under game_date. Keep only season_type=regular, exclude did_not_play, and deduplicate by game identifier. A zero-point appearance remains zero. A missing points key is unknown and is excluded, not filled with zero. Sort the accepted games from oldest to newest before deriving features.

```
# These are actual response fields, not guessed CSV column names.
points = game["stats"].get("points")
game_id = game["stats_event_id"]
game_date = game["game_date"]
season = game["season"]
```

## 4. Work through one five-game points forecast

Here is a synthetic example to make the arithmetic inspectable. Suppose the five earlier points totals are 18, 24, 20, 30 and 23. Their sum is 115, so the rolling forecast is 23.0 points. If all earlier games that season sum to 442 points over 20 games, the season-average baseline is 22.1. These numbers illustrate the method; they are not an observed player record or a betting recommendation.

| Quantity | Worked value | When it is available |
| --- | --- | --- |
| Previous five-game points mean | 115 / 5 = 23.0 | Before the target game, after those earlier games finish |
| Previous season-to-date mean | 442 / 20 = 22.1 | Before the target game |
| Target game final points | For example, 26 | Only after the target game; label, never a feature |
| Rolling absolute error | \|26 − 23.0\| = 3.0 | After the target game, for evaluation |

## 5. Evaluate in chronological walk-forward order

For each target game, calculate both forecasts using only records with a strictly earlier game_date in the same season. Exclude every game on the target date when completion times are unavailable. The target’s own points must not affect its forecast. Then move to the next game and repeat; the earlier result can now inform the later forecast.

The script reports mean absolute error (MAE) for both baselines over exactly the same evaluated games: add the absolute errors and divide by the evaluated-game count. Lower MAE means a smaller average points error on that window. The script withholds MAE when fewer than 20 worked forecasts are available, while still exporting their rows. This is a tutorial guard, not a scientifically sufficient sample-size rule. MAE does not mean higher over/under accuracy, calibrated probabilities or positive returns. If fewer than five earlier games are available, it prints no score for that game instead of manufacturing a prediction.

```
earlier = [g for g in history
           if g["season"] == target_season and g["date"] < target_date]
forecast = sum(g["points"] for g in earlier[-5:]) / 5
absolute_error = abs(final_points - forecast)
```

This is a retrospective walk-forward baseline using today’s stored box-score revisions. A later stat correction may change an older value. It is not proof of exactly which revision a live system knew that day. Archive daily inputs if that distinction matters. If you tune the five-game window or add features after seeing these errors, reserve later untouched dates for a separate final evaluation.

## 6. Compare the forecast with a current Underdog Fantasy line

The script also requests /projections with league=NBA, stat=points, payout_tier=standard and view=full. It requires league=NBA, an exact player-name match after the API search, market.stat=points, market.period=Full game, an available standard payout_tier selection, an active offer and a future event.starts_at. Half-game and quarter lines are excluded. It excludes today’s game logs when constructing this pregame feature. With a 23.0-point forecast and a current 24.5-point line, the difference is −1.5 points. That is a difference between a stat estimate and a threshold, not an under probability or an expected-value calculation.

Each comparison includes the projection identifier and observed_at. The script skips comparisons unless board pages report fresh, and skips offers observed more than ten minutes ago. That is a conservative tutorial filter, not a freshness guarantee. If the player is not on the board, the start time has passed, or the selected logs do not include enough earlier games in the upcoming season, the comparison list stays empty. A model trained on a prior season is not silently reused as a current-season forecast.

## 7. Save the result and decide what to improve

The script saves the returned input rows in nba-model-game-logs.json and writes nba-model-walk-forward.csv with one worked forecast per eligible game and nba-model-metadata.json with coverage, sample limits, current-line comparisons and the error summary. It never writes the API key. Every request sends X-User-Request describing this task; those summaries are retained for 35 days to improve the product. Keep personal information and secrets out of request context.

- Inspect the evaluated-game count and date range before interpreting the MAE. A handful of Free sample forecasts is a parser boostedstration, not a trustworthy performance estimate.
- Use minutes from earlier games to investigate role changes, not the target game’s final minutes. Any extra injury, starter or matchup feature needs its own availability timestamp.
- Compare new features against both unchanged baselines on later untouched games. Keep the target definition and evaluation rows consistent.
- For a classifier against historical offered lines, use the separate graded training-data workflow. Do not infer historical Underdog Fantasy thresholds from box-score averages.

## What the paid plan actually changes

Developer costs $49/month and unlocks all loaded player-game seasons and pagination beyond the Free ten-game cap, plus the full available graded training set rather than the few labelled sample rows Free gets in its 402 answer. It does not create missing leagues, guarantee enough rows for a robust model, or add Underdog Fantasy lines before observation began. Try the useful sample first and upgrade only when its returned limits prevent the training window you need.

This article is a complete first baseline, not a promised winning strategy. A better stat forecast does not by itself establish an edge after payouts, correlated selections, void rules, promotions or actual availability.

## Try it

[**Run a bounded demo** Inspect fictional rows without a key.](https://underdogapi.com/playground) [**Download the starter kit** Guarded clients, samples and Postman requests.](https://underdogapi.com/developers/starter-kit)

Endpoint docs: [GET /api/v1/training-set](https://underdogapi.com/docs#training-set) [Plans and limits](https://underdogapi.com/pricing)

## Frequently asked questions

What is the main data constraint when I build a measured nba research workflow?

Begin with coverage, inspect a sample, choose a chronological split and compare a simple baseline. Report sample size and excluded rows; do not promise profitability.

Can a backtest guarantee future profits?

No. A backtest describes a chosen sample under stated assumptions. Missing observations, changing rules and future conditions can all change its result.

## Continue building

[Guide **API reference**](https://underdogapi.com/docs) [beginner **Read Underdog data in Python**](https://underdogapi.com/underdog-api-python) [beginner **Try the Underdog API for free**](https://underdogapi.com/underdog-api-free) [data **Prepare data for a prop model**](https://underdogapi.com/underdog-prop-model-data)

[All developer resources](https://underdogapi.com/resources) [Pricing](https://underdogapi.com/pricing)

## References

- [Underdog API reference](https://underdogapi.com/docs)
- [OpenAPI contract](https://underdogapi.com/openapi.json)

On this page

[Not for](https://underdogapi.com/build-an-nba-prop-model#not-for) [1. Choose one prediction target](https://underdogapi.com/build-an-nba-prop-model#1-choose-one-prediction-target-0) [2. Import real regular-season game logs](https://underdogapi.com/build-an-nba-prop-model#2-import-real-regular-season-game-logs-3) [3. Clean points without turning missing values into zeros](https://underdogapi.com/build-an-nba-prop-model#3-clean-points-without-turning-missing-values-into-zeros-7) [4. Work through one five-game points forecast](https://underdogapi.com/build-an-nba-prop-model#4-work-through-one-five-game-points-forecast-10) [5. Evaluate in chronological walk-forward order](https://underdogapi.com/build-an-nba-prop-model#5-evaluate-in-chronological-walk-forward-order-13) [6. Compare the forecast with a current Underdog Fantasy line](https://underdogapi.com/build-an-nba-prop-model#6-compare-the-forecast-with-a-current-underdog-fantasy-line-18) [7. Save the result and decide what to improve](https://underdogapi.com/build-an-nba-prop-model#7-save-the-result-and-decide-what-to-improve-21) [What the paid plan actually changes](https://underdogapi.com/build-an-nba-prop-model#what-the-paid-plan-actually-changes-24) [FAQ](https://underdogapi.com/build-an-nba-prop-model#faq)

[Playground](https://underdogapi.com/playground) [Plans and limits](https://underdogapi.com/pricing)

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