# Your first call.

> Keyless demo, then a free key, then an authenticated call. What counts as a request, what streaming costs, what you may redistribute, and how support works, in plain words. 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/first-call

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

Start here



For developers checking whether Underdog data here fits a project. Run the demo with no account, get a free key with no card, then read real lines. Not for placing entries or reading an Underdog account; this API is independent, read-only market data.

## 1. Call the demo. No key, no account.

cURL

```
curl 'https://underdogapi.com/api/v1/demo/projections?league=NBA&limit=5'
```

Fictional players, the live response shape, zero credits. Every demo row has `is_demo: true`. Demo routes cover projections, history, changes, coverage, export and payouts.

## 2. Get a free key.

[Create an account](https://underdogapi.com/sign-up) with an email address and no card, then copy a key from [API keys](https://underdogapi.com/dashboard/keys). It is shown once. Coding agents can request one with your approval through [agents.md](https://underdogapi.com/agents.md).

Keep it in your environment

```
export UNDERDOG_API_KEY='your saved key'
```

## 3. Make the same call with your key.

cURL · 1 credit

```
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'
```

You should see real rows, `meta.mode` of `live`, and `observed_at` on each row. Check `meta.source_status` before relying on them. Empty? Read the free [coverage endpoint](https://underdogapi.com/docs#coverage) to see what is on the board. Send the key in the header from your server only.

Next: the [live props](https://underdogapi.com/underdog-props-api), [historical lines](https://underdogapi.com/underdog-historical-data) or [streaming and webhooks](https://underdogapi.com/underdog-api-webhooks) page, whichever matches your job.

## What counts as a request

New plans meter credits. Each page is a separate request, admitted at the rows you ask for and charged for the rows it served, every started 100, at least one page.

| Call | Credits |
| --- | --- |
| Compact board, 1,000 rows /api/v1/projections?league=NBA&view=compact&limit=1000 | 10 |
| Compact board, default page /api/v1/projections?league=NBA&view=compact | 1 |
| Full board rows, 200 /api/v1/projections?league=NBA&limit=200 | 6 |
| Change feed, default page /api/v1/changes | 1 |
| Per-side multipliers, default page /api/v1/multipliers?league=NBA | 1 |
| Board as of a past moment, 100 rows /api/v1/board?league=NBA&as_of=2026-11-01T23%3A00%3A00Z&limit=100 | 10 |
| Training set, default page /api/v1/training-set?league=NBA | 10 |
| One live-feed connection /api/v1/stream | 2 |
| Coverage /api/v1/coverage | 0 |
| Any demo endpoint /api/v1/demo/projections | 0 |
| Any error, or an unchanged 304 | 0 |

- **Monthly:** 100 credits on Free, 10,000 on Developer, 50,000 on Production, 250,000 on Scale, shared across a workspace's keys. Resets on the first of the month, UTC.
- **Per minute:** 20, 60, 120 and 180 requests. Over a limit you get a 429 and no automatic overage charge.
- **Save credits:** send the last `ETag` as `If-None-Match`. Read `X-Credits-Charged` and `X-Credits-Remaining` on each response, or `meta.credits_charged` and `meta.remaining` in the body. For a job that runs on a schedule, see [scheduled jobs](https://underdogapi.com/docs/scheduled-jobs).
- **Older accounts:** an existing request-based subscription keeps its purchased allowance, and `X-Usage-Unit` says which you have.

The full schedule and a calculator are on [credit costs](https://underdogapi.com/credits). Quote any call for free at `/api/v1/credit-costs?path=`.

## How streaming costs

The live feed costs 2 credits per connection, and a connection lasts up to 285 seconds. You pay for connecting, not for events. One stream held open for a 30-day month is about 18,200 credits. Free's whole allowance buys about 3 hours of one stream, Developer's about 16 days, Production's about 2.7 and Scale's about 13.7 streams held open all month. Delay is 300 seconds on Free, 0 on Developer and none added on Production or Scale, which is not the same as instant. Signed webhooks are on Production and Scale and are not metered in credits. [Read the details](https://underdogapi.com/underdog-api-webhooks).

## Redistribution rights

This is a plain summary. The [Terms](https://underdogapi.com/terms) are what bind you.

- **You may** build apps, tools, models, alerts and analysis on the data, and show it to your own users inside your product.
- **You may not** resell, sublicense or redistribute the raw feeds, bulk history or exports as a data product of your own, unless a written licence from us allows it.
- **You may not** share keys with other people or companies, or suggest that we or Underdog endorse you.
- **Need more volume?** Scale, the top plan, is $499 a month for 250,000 credits and 1,000,000 historical rows. See [pricing](https://underdogapi.com/pricing).

## Support

- Write to support@underdogapi.com. Include the path, the response status and the time. Never send your key.
- Tell us what data you needed with `POST /api/v1/feedback`. It needs no key and spends no quota.
- Read [status](https://underdogapi.com/status), [reliability](https://underdogapi.com/reliability) and [incidents](https://underdogapi.com/incidents) for the state of the service.
- No plan includes an SLA or a guaranteed response time. If you need one, ask before you build on it.

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

[Reference **Schema glossary** *Fields, null meanings and sample JSON.*](https://underdogapi.com/docs/schema-glossary) [Decide **When to choose this API** *And when a broad odds API is the better start.*](https://underdogapi.com/compare/when-to-choose-us) [Plans **Pricing** *Free, Developer, Production and Scale.*](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
