# Underdog API in Python

> Underdog API Python guide: install requests, fetch Underdog Fantasy pick'em lines and multipliers, page the whole board, load it into pandas, export CSV and read line history. Copy-paste code. 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-api-python

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

Python guide · updated November 13, 2026



Short answer: Underdog Fantasy has no official Python package or public API, so in Python you call Underdog API's REST endpoint GET https://underdogapi.com/api/v1/projections with requests and a free key (100 credits a month, no card): it returns every current Underdog pick'em line as JSON, with the Higher and Lower payout multipliers kept separate, and pages with meta.next_cursor.

## Facts

| Official Underdog Python SDK | None. Underdog Fantasy does not publish a developer API or package. |
| --- | --- |
| What to install | pip install requests (pandas optional). The standard library (urllib) also works. |
| Endpoint | GET https://underdogapi.com/api/v1/projections |
| Auth | Header Authorization: Bearer ud_... ; keep the key in the UNDERDOG_API_KEY environment variable |
| Page size | limit up to 200 full rows (1,000 with view=compact); follow meta.next_cursor until it is null |
| Cost | 3 credits per 100 full rows, 1 with view=compact; free plan 100 credits a month |
| No-key test | https://underdogapi.com/api/v1/demo/projections returns fictional rows in the live shape |
| Not the same as | Underdog Protocol (a Solana NFT SDK) and Underdog.io (a jobs marketplace): different companies, different APIs |

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

## 1. Install and set your key

One dependency. The key stays in the environment, never in code.

shell

```
pip install requests pandas
export UNDERDOG_API_KEY=ud_...   # free key: https://underdogapi.com/sign-up
```

## 2. First call: five NBA lines

Each row is one Underdog line. selections holds one entry per side with its own multiplier.

python

```
import os
import requests

r = requests.get(
    "https://underdogapi.com/api/v1/projections",
    params={"sport": "NBA", "limit": 5},
    headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"},
    timeout=30,
)
r.raise_for_status()
for line in r.json()["data"]:
    sides = {s["side"]: s for s in line["selections"]}
    print(line["player"]["name"], line["market"]["stat"], line["line"],
          "higher", sides["higher"]["payout_multiplier"],
          "lower", sides["lower"]["payout_multiplier"])
```

A side Underdog does not offer comes back with `available: false` and a null `payout_multiplier`, so a Higher-only line never looks like a 1.0x Lower. Check `meta.source_status` and each row’s `observed_at` before showing a line as current.

## 3. Page through the whole board

Use limit=200 and follow meta.next_cursor until it is null.

python

```
def board(sport, page_size=200):
    """Every current line for one league, page by page."""
    params = {"sport": sport, "limit": page_size}
    while True:
        r = requests.get(f"https://underdogapi.com/api/v1/projections", params=params,
                         headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"}, timeout=30)
        r.raise_for_status()
        page = r.json()
        yield from page["data"]
        if not page["meta"].get("next_cursor"):
            return
        params["cursor"] = page["meta"]["next_cursor"]

lines = list(board("NFL"))
print(len(lines), "NFL lines")
```

## 4. Load it into pandas

python

```
import pandas as pd

rows = []
for line in board("NBA"):
    sides = {s["side"]: s for s in line["selections"]}
    rows.append({
        "player": line["player"]["name"], "team": line["player"]["team"],
        "stat": line["market"]["stat"], "line": line["line"],
        "higher_x": sides.get("higher", {}).get("payout_multiplier"),
        "lower_x": sides.get("lower", {}).get("payout_multiplier"),
        "starts_at": line["event"]["starts_at"],
    })
df = pd.DataFrame(rows)
# Boosted sides pay more than 1.0x, discounted sides less. A missing Lower is NaN, not 1.0.
print(df[df.higher_x > 1].sort_values("higher_x", ascending=False).head(10))
```

## 5. Line history for one line

Every recorded line and multiplier change, oldest first.

python

```
line_id = lines[0]["id"]  # stable through line moves
r = requests.get(f"https://underdogapi.com/api/v1/projections/{line_id}/history",
                 params={"limit": 50},
                 headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"}, timeout=30)
r.raise_for_status()
for change in r.json()["data"]:
    print(change["observed_at"], change["line"], change["line_moved"],
          [(s["side"], s["payout_multiplier"]) for s in change["selections"]])
```

## 6. Export CSV in one call

Up to 1,000 rows per call as text/csv; follow the cursor for more.

python

```
r = requests.get(f"https://underdogapi.com/api/v1/export",
                 params={"sport": "NFL", "limit": 1000, "format": "csv"},
                 headers={"Authorization": f"Bearer {os.environ['UNDERDOG_API_KEY']}"}, timeout=60)
r.raise_for_status()
open("underdog_nfl.csv", "w").write(r.text)
```

Prefer a finished script? [underdog-board-to-csv.py](https://underdogapi.com/examples/underdog-board-to-csv.py) pages the whole board for one league or all of them and writes a CSV, with rate-limit handling. Also available: the [standard-library quickstart](https://underdogapi.com/examples/underdog-quickstart.py), a [Jupyter notebook](https://underdogapi.com/examples/underdog-quickstart.ipynb) and the [full starter kit](https://underdogapi.com/developers/starter-kit).

## Errors and retries

Errors are JSON: {"error": {"code", "message"}}. Failed calls cost no credits.

| Status and code | Meaning | What your code should do |
| --- | --- | --- |
| 401 INVALID_API_KEY | Missing, malformed or revoked key | Fix the header; do not retry unchanged |
| 400 | Invalid query parameter | Read error.message and correct the parameter |
| 429 RATE_LIMIT_EXCEEDED | Per-minute limit | Sleep for the Retry-After header, then retry |
| 429 MONTHLY_QUOTA_EXCEEDED | Monthly credits used up | Stop; wait for the reset or upgrade. Never retry in a loop |
| 403 | Plan limit or restricted account | Read error.code; the call needs a different plan |
| 503 | Temporary outage | Retry with backoff; check meta.source_status on the next 200 |

## Live updates without polling

For a bot or dashboard, poll `GET /api/v1/changes` with the cursor from your last call (1 credit per 100 changes), or hold the server-sent stream at `/api/v1/stream` open with any SSE client. The [changes watcher script](https://underdogapi.com/examples/underdog-changes-watch.py) shows the cursor loop.

## Questions

Is there an official Underdog Fantasy API for Python?

No. Underdog Fantasy does not publish a public developer API or a Python package. Python code reads Underdog lines either by calling its private app endpoints (undocumented and liable to break) or through a hosted service such as Underdog API, which documents its endpoints and keeps a stable schema.

Is there a pip package for the Underdog API?

You do not need one. The API is plain HTTPS and JSON, so requests (or urllib from the standard library) is enough. A ready-to-run script that pages the whole board and writes CSV is at underdogapi.com/examples/underdog-board-to-csv.py.

How do I get Underdog projections into a pandas DataFrame?

Page through GET /api/v1/projections, flatten each row (player, stat, line and the Higher and Lower multipliers from selections) into a dict, and pass the list to pd.DataFrame. The code on this page does exactly that.

Can I try it in Python without a key?

Yes. Call https://underdogapi.com/api/v1/demo/projections with no Authorization header. It returns fictional rows in the same shape as the live endpoint, so your parser works unchanged when you add a key.

How do I get Underdog line history in Python?

Call GET /api/v1/projections/{id}/history with a line id from the board. Each row is one recorded change with its time, the line and both sides' multipliers, and line_moved tells you whether the number itself moved.

Is this the Underdog Protocol API?

No. Underdog Protocol is an unrelated Solana NFT developer platform. This page is about Underdog Fantasy pick'em data.

[Script **Underdog scraper in Python** *Whole board to CSV.*](https://underdogapi.com/underdog-scrapers) [Reference **Projections endpoint** *Every parameter and field.*](https://underdogapi.com/underdog-projections-api) [Model **Build an NBA prop model** *Training rows and grading.*](https://underdogapi.com/build-an-nba-prop-model) [Compare **Underdog API alternatives** *Every provider, dated.*](https://underdogapi.com/underdog-api-alternatives)

Underdog API is an independent data service. It is not affiliated with, endorsed by or operated by Underdog Fantasy or any company named on this page.

## References

- [Underdog API reference](https://underdogapi.com/docs)
- [OpenAPI contract](https://underdogapi.com/openapi.json)
- [Keyless demo response](https://underdogapi.com/api/v1/demo/projections?limit=1)
- [requests documentation](https://requests.readthedocs.io/)

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