# Understand recorded Underdog history

> Inspect retained observations before choosing a backtest window. Opening means first recorded, not necessarily the original source opening. No historical 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/underdog-historical-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 understand recorded underdog history.

Inspect retained observations before choosing a backtest window.

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

## What is in the record now

Lines recorded **57,136**

Line moves **51,551**

Leagues **18**

Recorded since **Nov 6, 23:15 UTC**

| League | Lines | Moves | Graded |
| --- | --- | --- | --- |
| [College Football](https://underdogapi.com/line-moves/cfb) | 9,499 | 18,585 | 1,686 |
| [NFL](https://underdogapi.com/line-moves/nfl) | 10,443 | 18,249 | 1,564 |
| [NBA](https://underdogapi.com/line-moves/nba) | 11,308 | 9,638 | 1,894 |
| [College Basketball](https://underdogapi.com/line-moves/cbb) | 3,017 | 1,458 | 1,390 |
| [NHL](https://underdogapi.com/line-moves/nhl) | 11,672 | 1,378 | 4,740 |
| [CS](https://underdogapi.com/line-moves/cs) | 1,781 | 1,076 | — |
| [Tennis](https://underdogapi.com/line-moves/tennis) | 3,627 | 615 | — |
| [FIFA](https://underdogapi.com/line-moves/fifa) | 3,397 | 179 | — |
| [DOTA](https://underdogapi.com/line-moves/dota) | 1,005 | 128 | — |
| [MMA](https://underdogapi.com/line-moves/mma) | 516 | 128 | — |
| [PGA Golf](https://underdogapi.com/props/pga) | 127 | 57 | — |
| [League of Legends](https://underdogapi.com/props/lol) | 170 | 31 | — |
| INTLBASKETBALL | 389 | 14 | — |
| CFL | 76 | 12 | — |

Updated hourly. A line move is a change we recorded between board checks. [Hit rates from the graded record](https://underdogapi.com/hit-rates)

## Start with the data contract

Opening means first recorded, not necessarily the original source opening. No historical start date is promised before collection exists.

## Choose an observation cutoff

Use a stable market id and retain the complete observation sequence. A price-only change can create history without a numeric line move. Select the last observation at or before your cutoff.

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

```
const PATH = `/api/v1/projections/${encodeURIComponent(process.env.MARKET_ID)}/history?limit=50`;
const response = await fetch("https://underdogapi.com" + PATH, {
  headers: { Authorization: "Bearer " + process.env.UNDERDOG_API_KEY }
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const page = await response.json();
console.log(page.meta);
const cutoff = Date.parse(process.env.OBSERVATION_CUTOFF);
const prior = page.data.filter(v => Date.parse(v.observed_at) <= cutoff);
prior.sort((a, b) => Date.parse(a.observed_at) - Date.parse(b.observed_at));
console.log("Last retained observation on this page:", prior.at(-1) ?? null);
console.log("More history pages:", page.meta.next_cursor);
```

## 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 projections/{id}/history 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/projections/{id}/history](https://underdogapi.com/docs#history) [Plans and limits](https://underdogapi.com/pricing)

## Frequently asked questions

What is the main data constraint when I understand recorded underdog history?

Opening means first recorded, not necessarily the original source opening. No historical start date is promised before collection exists.

Can older box scores extend offered-line history?

No. A box score contains the final statistic, not the earlier offered line and side prices. History begins only when those observations were retained.

## Continue building

[Guide **API reference**](https://underdogapi.com/docs) [beginner **Underdog Fantasy API: what exists and which to use**](https://underdogapi.com/underdog-fantasy-api) [data **Read Higher/Lower player props**](https://underdogapi.com/underdog-props-api)

[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-historical-data#not-for) [Start with the data contract](https://underdogapi.com/underdog-historical-data#start-with-the-data-contract-0) [Choose an observation cutoff](https://underdogapi.com/underdog-historical-data#choose-an-observation-cutoff-2) [Run a bounded integration example](https://underdogapi.com/underdog-historical-data#run-a-bounded-integration-example-4) [Verify the response and its limits](https://underdogapi.com/underdog-historical-data#verify-the-response-and-its-limits-7) [Continue with the reference](https://underdogapi.com/underdog-historical-data#continue-with-the-reference-9) [FAQ](https://underdogapi.com/underdog-historical-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
