# Source event state and participant identities

Read ESPN-reported state and native team identities for a verified stored GetOdds event. Keep receipt times, source scope and identity limits explicit.

Canonical page: https://getoddsapi.com/docs/event-metadata

## 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/event-metadata
Reviewed: 2026-11-07 UTC

Read ESPN-reported state and native team identities for a verified stored GetOdds event. Keep receipt times, source scope and identity limits explicit.

## Start with a stored event

Use GET /api/v1/events to obtain a DraftKings-via-ESPN event ID. All metadata routes require a bearer key with the draftkings grant, and the event must exist in that source store before GetOdds contacts ESPN. Caller-provided arbitrary upstream URLs are not accepted.

Each successful read costs one shared credit and consumes the existing request allowance. Each call makes at most one upstream request with a five-second timeout and a two-MiB response limit. Missing events return 404; malformed or unavailable metadata returns 503.

## Read source-reported event state

GET /api/v1/events/{id}/state returns one row with state (pre, in or post), completed, source_status and the source-scheduled starts_at. These fields come directly from the matching ESPN event response, not from an inference based on start time.

The metadata includes observed_at (receipt time) and source_updated_at:null. The receipt does not prove when ESPN last updated its own data. This lookup is not a continuous live-events index or a result/settlement service.

```bash
curl --fail-with-body "https://getoddsapi.com/api/v1/events/espn-draftkings:espn:NFL:401873038/state" \
  -H "Authorization: Bearer $GETODDS_API_KEY"
```

## Resolve teams within an event

GET /api/v1/participants?event_id=ID returns the two verified home and away teams. Each row includes the raw native_id, identity_provider:espn, league identity scope and an ID such as espn:NFL:team:1. This is an ESPN-native identifier, not a canonical identity across sportsbooks.

GET /api/v1/participants/{id}?event_id=ID returns one participant only when that native ID is present in the requested event. The event filter is required. These routes do not expose a global team directory, player roster, logos or bookmaker-native market/outcome mappings.

## Keep metadata separate from prices and grading

Metadata is fetched from ESPN after the retained DraftKings event has been verified. A source-reported completed flag does not establish sportsbook settlement, voids, corrections or market-specific rules. Do not use these fields alone to grade wagers.

The hourly DraftKings price collector currently drops event-state and participant-ID fields before storage. This bounded metadata lookup adds those observations without modifying that collector or pretending past lifecycle history has been retained.

## Questions

### Are these universal participant IDs?

No. They are ESPN native team IDs scoped by league. Cross-provider reconciliation remains separate work.

### Does completed mean a bet is settled?

No. It is the source-reported event flag. Bookmaker rules, verified results and corrections are still required for settlement.

### Will unknown source events trigger a network lookup?

No. The event must first match the existing DraftKings-via-ESPN store under the authorized source grant.

## Sources

- [GetOdds OpenAPI](https://getoddsapi.com/openapi.json)
- [Stored sportsbook API](https://getoddsapi.com/docs/sportsbook)
- [ESPN source example](https://site.api.espn.com/apis/site/v2/sports/football/nfl/summary?event=401873038)

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.