# League discovery, historical events and market summaries

Query retained leagues, search scheduled historical events and summarize matching DraftKings market lines with explicit coverage limits.

Canonical page: https://getoddsapi.com/docs/market-summaries

## Free API key

Get a free GetOdds API key: **1,000 requests per UTC day and 60 per minute, no card**. One key covers REST and the hosted MCP server.

Sign up: https://getoddsapi.com/sign-up?ref=ai-claudebot

## Quickstart

1. Create an account at https://getoddsapi.com/sign-up?ref=ai-claudebot, open https://getoddsapi.com/dashboard and issue a key with the sources you need (draftkings, fanduel, betrivers, prizepicks or underdog). Keep it in a server environment variable named GETODDS_API_KEY.
2. Read current DraftKings NBA spreads with curl:

```bash
curl --fail-with-body "https://getoddsapi.com/api/v1/odds?sport=NBA&market=spread&fresh_only=true&limit=50" \
  -H "Authorization: Bearer $GETODDS_API_KEY"
```

3. The same request in Python (standard library only):

```python
import json, os, urllib.request

req = urllib.request.Request(
    "https://getoddsapi.com/api/v1/odds?sport=NBA&market=spread&fresh_only=true&limit=50",
    headers={"Authorization": "Bearer " + os.environ["GETODDS_API_KEY"]},
)
with urllib.request.urlopen(req) as res:
    rows = json.load(res)["data"]
for row in rows:
    print(row["away"], "at", row["home"], row["side"], row["line"], row["american"], row["observed_at"])
```

4. Check `observed_at`, `age_seconds` and `stale` on every row before using a price. Full reference: https://getoddsapi.com/docs

## Use with Claude (MCP)

```bash
claude mcp add --transport http getodds https://getoddsapi.com/api/mcp \
  --header "Authorization: Bearer $GETODDS_API_KEY"
```

The MCP tools follow the key's source grants and share its allowance. Setup guide: https://getoddsapi.com/use-with-claude

## Pricing

| Plan | Allowance | Price |
| --- | --- | --- |
| Free key | 1,000 requests a day, 60 a minute | $0, no card |
| Developer Bundle | 10,000 requests or credits a month on each of four sources | $149 a month |

Free development allowance: 1,000 requests per UTC day and 60 per minute per account, with no payment step. Paid: the Developer Bundle at $149 per month, with 10,000 monthly requests or credits on each of four sources.
Details: https://getoddsapi.com/bundle

## Guide


Canonical: https://getoddsapi.com/docs/market-summaries
Reviewed: 2026-11-07 UTC

Query retained leagues, search scheduled historical events and summarize matching DraftKings market lines with explicit coverage limits.

## Access and limits

Use a bearer API key with the draftkings grant. Each successful read costs one shared credit and uses the existing request limits. All five endpoints accept limit (1–200, default 50), offset (0–10,000), and source=draftkings. Unknown or repeated filters return 400. Offset pagination is not a frozen snapshot.

## Discover retained leagues

GET /api/v1/leagues returns league IDs, names, sport categories, retained event counts and upcoming scheduled event counts. Optional sport is basketball, american-football, ice-hockey, baseball or soccer. upcoming_only=true filters to leagues with a scheduled start after the request time. Counts describe stored observations, not guaranteed live coverage.

```bash
curl --fail-with-body https://getoddsapi.com/api/v1/leagues?sport=basketball \
  -H "Authorization: Bearer $GETODDS_API_KEY"
```

## Find historical scheduled events

GET /api/v1/historical/events requires league (NBA, NFL, NHL, NCAAB, NCAAF, MLB, EPL or MLS), from and to. Use UTC timestamps ending in Z. The interval includes from and excludes to, must span no more than 31 days, and cannot end in the future. Add q (2–100 characters) at /api/v1/historical/events/search for literal, case-insensitive home or away team matching.

These are retained scheduled events. Their completion state is unknown, finished_events_verified is false, and archive_complete is false. They are not a results feed or a guaranteed historical archive.

## Summarize matching market lines

GET /api/v1/odds/summary requires event_id. For up to 20 distinct IDs use /api/v1/odds/summary/multi?event_ids=id1,id2. Both accept market=moneyline, spread or total. At most 2,000 fresh input offers are allowed; a larger selection returns 422. Missing events return no invented rows.

Quotes are grouped by event, market, period and matching line. Spread reference_line is expressed from the home side; totals use the recorded total. Only observations captured within the last 15 minutes are included.

Only one independent bookmaker is connected: DraftKings via ESPN. Best, average, median and worst prices therefore currently equal that one recorded quote. cross_book_comparison is false. This is not a cross-book consensus product.

normalized_price_probability uses (1 / decimal) divided by the sum across matching sides. It is null unless expected sides are present and capture timestamps are within 60 seconds. Soccer moneyline requires home, away and draw; totals require over and under. This mathematical normalization does not establish true win probability or settlement rules.

## Handle unavailable data

An empty array means no matching retained observations. A 503 means the source or validation failed, and the request is not charged a data credit. Never replace missing quotes, outcomes or event states with fabricated values.

- [Sportsbook gateway](https://getoddsapi.com/docs/sportsbook): Core event, offer and retained-change contracts.
- [Search and price changes](https://getoddsapi.com/docs/sportsbook-search): Batch reads, updated offers and dropping prices.

## Questions

### Is this full competitor parity?

No. Cross-book summaries require additional independent price feeds, and a finished-event archive requires verified event state and retention coverage.

### Does normalization predict who wins?

No. It removes the recorded implied-probability sum mathematically; it does not estimate the true outcome likelihood.

### Are past scheduled events confirmed finished?

No. The current event store does not persist verified completion state.

## Sources

- [GetOdds OpenAPI](https://getoddsapi.com/openapi.json)
- [Gateway coverage](https://getoddsapi.com/capabilities.json)
- [Sportsbook query contract](https://getoddsapi.com/docs/sportsbook-search)

Independent product; not affiliated with the operators named. No picks or predicted profits.

---

GetOdds is an independent developer product and is not affiliated with any sportsbook or pick’em operator. Prices describe data, not betting advice.