# Prepare data for a prop model

> Join retained lines to outcomes without future leakage. Use chronological train/test splits. Missing grades and coverage gaps affect your denominator. A hi 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/underdog-prop-model-data

## 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 prepare data for a prop model.

Join retained lines to outcomes without future leakage.

[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)

Free answers the training set and game logs with a labelled sample and an upgrade link. This point-in-time example uses closing_observed_at and updated_at to avoid revision leakage; voids are excluded. Developer: $49/month unlocks the permitted archive, not unrecorded dates.

## Start with the data contract

Use chronological train/test splits. Missing grades and coverage gaps affect your denominator. A historical hit rate is descriptive, not a forecast.

## Separate features from labels

Use only information known by the prediction cutoff. Actual values, final minutes and grades belong to evaluation labels; closing data may be later than an earlier prediction.

## Run a bounded integration example

Keep the bearer token in a server environment. Snippets that refer to an existing page, rows or url are processing examples to apply after a successful response; replace any market or cutoff placeholder deliberately.

```
"""A small close-time probability baseline. Python 3; standard library only."""
import json
import math
import os
import time
from collections import defaultdict
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, HTTPRedirectHandler, build_opener

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        raise RuntimeError("Refusing to forward a credential to a redirect")

urlopen = build_opener(NoRedirect()).open

BASE = "https://underdogapi.com/api/v1"
FILTERS = {"league": "NBA", "stat": "points", "payout_tier": "standard", "limit": 1000}

def stamp(value):
    return datetime.fromisoformat(value.replace("Z", "+00:00"))

def download():
    headers = {
        "Authorization": "Bearer " + os.environ["UNDERDOG_API_KEY"],
        "X-User-Request": "Train and evaluate an NBA Points close-time probability baseline",
    }
    rows, pages, seen = [], [], set()
    cursor = None
    while True:
        if len(pages) >= 100:
            raise RuntimeError("Stop after 100 pages; narrow the recorded date window.")
        params = dict(FILTERS)
        if cursor:
            params["cursor"] = cursor
        request = Request(BASE + "/training-set?" + urlencode(params), headers=headers)
        with urlopen(request, timeout=30) as response:
            page = json.load(response)
        if page.get("meta", {}).get("grading_status") == "pending_review":
            raise RuntimeError("Graded training data is unavailable pending review.")
        rows.extend(page["data"])
        pages.append(page["meta"])
        if page["meta"].get("plan_limit"):
            # A Free sample is useful for inspection, not a complete training archive.
            break
        cursor = page["meta"].get("next_cursor")
        if not cursor:
            break
        if cursor in seen:
            raise RuntimeError("Repeated pagination cursor")
        seen.add(cursor)
        time.sleep(1.1)
    snapshot = {
        "captured_at": datetime.now(timezone.utc).isoformat(),
        "filters": FILTERS, "pages": pages, "data": rows,
    }
    with open("training-snapshot.json", "w") as file:
        json.dump(snapshot, file, indent=2)
    if any(meta.get("plan_limit") for meta in pages):
        raise RuntimeError("Saved Free sample. Full archive evaluation needs an unrestricted export.")
    return rows

def eligible(rows):
    # One league, market, period and tier; no mixing incomparable targets.
    kept = {}
    for row in rows:
        if (row.get("league") != "NBA" or str(row.get("stat", "")).casefold() != "points"
                or row.get("higher_payout_tier") != "standard" or row.get("lower_payout_tier") != "standard" or row.get("period") not in ("full_game", "Full game")
                or row.get("close_confidence") != "confirmed"
                or row.get("status") != "graded" or row.get("result") not in ("higher", "lower")):
            continue
        try:
            line = float(row["closing_line"])
            start, observed = stamp(row["starts_at"]), stamp(row["closing_observed_at"])
            stamp(row["updated_at"])
            if not math.isfinite(line) or observed > start:
                continue
        except (ValueError, TypeError, KeyError):
            continue
        old = kept.get(row["projection_id"])
        if old is None or stamp(row["updated_at"]) > stamp(old["updated_at"]):
            kept[row["projection_id"]] = row
    return sorted(kept.values(), key=lambda row: (row["game_date"], row["starts_at"], row["projection_id"]))

def chronological_split(rows):
    dates = sorted({row["game_date"] for row in rows})
    if len(dates) < 5:
        raise ValueError("Need at least five game dates for this educational split; more history is preferable.")
    valid_date, test_date = dates[int(len(dates) * 0.6)], dates[int(len(dates) * 0.8)]
    valid_cutoff = min(stamp(row["starts_at"]) for row in rows if row["game_date"] >= valid_date)
    test_cutoff = min(stamp(row["starts_at"]) for row in rows if row["game_date"] >= test_date)
    train, valid, test = [], [], []
    for row in rows:
        if row["game_date"] < valid_date:
            # Conservative: do not train on a result revision published after validation began.
            if stamp(row["updated_at"]) < valid_cutoff:
                train.append(row)
        elif row["game_date"] < test_date:
            if stamp(row["updated_at"]) < test_cutoff:
                valid.append(row)
        else:
            test.append(row)
    if not all((train, valid, test)):
        raise ValueError("An evaluation window is empty after timestamp checks; do not invent a score.")
    return train, valid, test

def label(row):
    return int(row["result"] == "higher")

def fit(train, strength):
    # Learn a smoothed higher rate by five-point closing-line bucket.
    prior = (sum(map(label, train)) + 1) / (len(train) + 2)
    groups = defaultdict(list)
    for row in train:
        groups[math.floor(float(row["closing_line"]) / 5)].append(label(row))
    rates = {bucket: (sum(values) + strength * prior) / (len(values) + strength)
             for bucket, values in groups.items()}
    return lambda row: rates.get(math.floor(float(row["closing_line"]) / 5), prior)

def brier(rows, predict):
    return sum((predict(row) - label(row)) ** 2 for row in rows) / len(rows)

def evaluate(rows):
    train, valid, test = chronological_split(eligible(rows))
    # Choose smoothing on validation, then keep test untouched until this final report.
    models = [(strength, fit(train, strength)) for strength in (5, 20, 100)]
    strength, model = min(models, key=lambda pair: brier(valid, pair[1]))
    constant = (sum(map(label, train)) + 1) / (len(train) + 2)
    report = {
        "rows": {"train": len(train), "validation": len(valid), "test": len(test)},
        "smoothing": strength,
        "validation_brier": brier(valid, model),
        "test_brier": brier(test, model),
        "test_constant_baseline_brier": brier(test, lambda row: constant),
        "test_dates": [test[0]["game_date"], test[-1]["game_date"]],
    }
    print(json.dumps(report, indent=2))
    return report

if __name__ == "__main__":
    evaluate(download())
```

## Verify the response and its limits

- Test invalid credentials and unavailable source data.
- Keep cursors, source status and timestamps with retained rows.
- Use coverage to confirm the requested sport and retained date window.

## Continue with the reference

Use the documented training-set contract for exact parameters and null meanings. A fictional demo validates a parser; it does not validate live collection or historical completeness.

## 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 prepare data for a prop model?

Use chronological train/test splits. Missing grades and coverage gaps affect your denominator. A historical hit rate is descriptive, not a forecast.

Can final minutes be a pre-game feature?

No. Realized minutes become known during or after the game. Using them in pre-game training inputs leaks future information and can overstate performance.

## Continue building

[Guide **API reference**](https://underdogapi.com/docs) [integration **Build a line-change notification bot**](https://underdogapi.com/underdog-discord-bot) [integration **Bring observations into a spreadsheet**](https://underdogapi.com/underdog-spreadsheet) [integration **Build a measured NBA research workflow**](https://underdogapi.com/build-an-nba-prop-model)

[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/underdog-prop-model-data#not-for) [Start with the data contract](https://underdogapi.com/underdog-prop-model-data#start-with-the-data-contract-1) [Separate features from labels](https://underdogapi.com/underdog-prop-model-data#separate-features-from-labels-3) [Run a bounded integration example](https://underdogapi.com/underdog-prop-model-data#run-a-bounded-integration-example-5) [Verify the response and its limits](https://underdogapi.com/underdog-prop-model-data#verify-the-response-and-its-limits-8) [Continue with the reference](https://underdogapi.com/underdog-prop-model-data#continue-with-the-reference-10) [FAQ](https://underdogapi.com/underdog-prop-model-data#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
