Odds API MCP
Read sports and racing events, bookmaker odds, results and line movement through 32 read-only MCP tools.
Documentation
Odds API docs
Make one server-side request first. Then move through coverage, events, streaming updates, limits, caching, and endpoint groups as needed.
Betfair in-play exchange odds are included on Builder, Live and Pro.
Step 1
Choose a plan
Choose a monthly USD plan for API access and production volume.
Step 2
Get your API key
Use your key in the docs or your own requests.
Step 3
Call the API
Start with meta, events, odds, bets, and results.
curl -H "X-API-Key: $ODDS_API_KEY" \
"https://api.odds-api.net/v1/events?sport=basketball&league=NBA&limit=25"
How to use these docs
Use the guide pages for integration decisions. Use the endpoint pages for live parameters, response codes, response body samples, stream formats, and request examples generated from the current OpenAPI schema.
Explore the global sports betting odds API Build a validated pandas model pipeline Compare Kalshi and Polymarket order books Build an NBA product with every available market Build an AFL product with fixtures, results and odds Integrate NBL game periods and player markets Build with A-League match results, goal and player odds Build an NRL product with fixtures, results and odds
Coverage
Discover what exists before requesting odds.
Build filters from coverage and metadata endpoints. This keeps UI filters honest and prevents background jobs from polling unsupported combinations.
/v1/coverage
Coverage snapshot
Use this for buyer-facing or internal coverage views across bookmakers, sports, leagues, and markets.
/v1/sports and /v1/leagues
Sport and league filters
Load these before event requests so your UI and jobs only ask for supported competitions.
/v1/bookmakers
Bookmaker filters
Inspect bookmaker keys, display names, countries, and availability before requesting odds.
Regional API guides
Use the country guides for regional bookmaker keys, market examples and request paths.
Events and odds
Page event lists, then load odds snapshots.
Keep event windows narrow, process pagination idempotently, and store freshness fields from odds snapshots so stale prices are visible.
Our pre-match bookmaker odds collection window covers events scheduled up to 7 days ahead. A fixture can appear before odds are available; check its odds snapshot for current markets.
/v1/events
Upcoming sports events
Use sport, league, start-time, status, limit, and cursor filters. Keep windows narrow in production.
/v1/racing/events
Racing events
Use the current event list as the source of truth. General bookmaker coverage in the UK, Ireland, or another region does not guarantee racing coverage there.
/v1/events/{event_id}/odds/snapshot
Initial odds state
Start every hot event view with a snapshot before polling deltas or opening a stream.
Discover current races first
Do not reuse an event ID or bookmaker filter from an example. List current races, copy an event_id, load its unfiltered odds snapshot, then reconnect with the snapshot's resume token.
GET /v1/racing/events?status=fetching&limit=25
GET /v1/racing/events/$RACE_EVENT_ID/odds
GET /v1/racing/events/$RACE_EVENT_ID/odds/stream?since=$RACE_RESUME_TOKEN&catchup=true
1
Authenticate server-side
Send X-API-Key from your backend. Do not expose keys in browser-visible code.
2
Discover coverage
Build filters from coverage, sports, leagues, bookmakers, and bookmaker country routes.
3
Page events
Call event routes with a narrow time window, limit, and cursor until next_cursor is empty.
4
Load odds snapshots
Fetch an event odds snapshot for initial state and store as_of_ts_ms, ttl_seconds, next_cursor, and resume.
5
Stream hot updates
For realtime products, connect to SSE or WebSocket streams after the snapshot and resume with since on reconnect.
6
Query history and results
Use history endpoints for line movement and result routes after events finish. Back off when data is settled.
SSE and WebSocket
Use streams after the initial snapshot.
Streams are best for hot odds views and alerting products. Snapshot first, apply deltas, and resync when the stream tells you the resume token is no longer available.
GET /v1/events/{event_id}/odds/snapshot
GET /v1/events/{event_id}/odds/stream?since=<resume>&catchup=true
GET /v1/events/{event_id}/odds/ws?since=<resume>&catchup=true
Compare REST, SSE and WebSocket delivery Build a sports prediction market feed
- Fetch a snapshot first and persist the `resume` token with the cached event state.
- Connect to `/stream` with Server-Sent Events or `/ws` with WebSockets. Use the same filters as the snapshot.
- Handle `delta` by applying changes idempotently. Store the newest `resume` after each accepted message.
- Treat `heartbeat` as a liveness signal. If no heartbeat or data arrives within your timeout, reconnect.
- On disconnect, reconnect with `since=<last_resume>` and `catchup=true` using jittered exponential backoff.
- On `resync`, reload the snapshot because the resume token is no longer available.
Rate limits
Poll slower by default and treat 429s as a control signal.
Prefer streams for realtime odds. When polling is required, keep filters narrow and let rate-limit headers shape worker behavior.
| Surface | Starting interval | Production notes |
|---|---|---|
| Sports, leagues, bookmakers | 6-24 hours | Coverage changes slowly. Refresh daily unless you are syncing a new catalog view. |
| Sports event lists | 5-15 minutes | Use tighter 1-5 minute polling only for active leagues or near-start windows. |
| Racing event lists | 1-5 minutes | Racing schedules change closer to jump. Keep the time window narrow. |
| Odds snapshots | 60-120 seconds | Use 15-30 seconds only for priority events when streams are not available. |
| Betting opportunity snapshots | 30-120 seconds | Poll faster only for alerting products with strict quota controls. |
| Results | 1-5 minutes after start | After final status appears, stop hot polling or move to a long retention refresh. |
Read the seven-day source-to-ingest timing study
429 backoff
- On HTTP 429, wait for `Retry-After` when present before sending another request to that route/key.
- When `Retry-After` is absent, start around 2 seconds and double up to about 60 seconds with random jitter.
- Use `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Bucket` when present to tune callers.
- If `/usage` shows the monthly API-credit quota is exhausted, stop retry loops and alert the account owner.
- Reduce polling breadth first: narrower leagues, fewer events, fewer bookmakers, and smaller page sizes.
Cache and pages
Cache by request shape and make cursors durable.
Each event's odds stream keeps its latest 100 changes. If your resume token has expired, load a fresh snapshot before reconnecting.
Use last-known-good odds with timestamps for UI surfaces, and only advance pagination checkpoints after a page is processed successfully.
Cache strategy
Key caches by request shape
Include endpoint path, event ID, normalized filters, page cursor, and API product context in the cache key.
Respect freshness fields
Use `ttl_seconds` when present. Always display or store `as_of_ts_ms` so stale odds are obvious.
Use streams to update hot caches
Apply stream deltas to the cached snapshot, but fall back to a fresh snapshot after `resync` or parse failure.
Prefer stale-while-revalidate for UI
Show the last good snapshot with a visible timestamp while refreshing in the background.
Pagination
- Pass `limit` within `/limits` response caps.
- Keep all filters identical between pages.
- Pass `next_cursor` into the next request's `cursor` parameter.
- Stop when `next_cursor` is missing, null, empty, or `0`.
- Persist the last completed cursor only after the page is processed successfully.
History and errors
Separate historical analysis from current odds.
Line movement is useful for audit and backtesting. Current odds can still be stale, suspended, limited, or unavailable.
History queries
- Enable History Lite before calling history endpoints on v2-priced API keys.
- Start from a current odds snapshot and copy the exact `selection_key` for the line you want to chart.
- Use `from_ts` and `to_ts` ISO8601 UTC windows for bounded history queries.
- Use `bookmakers`, `market_group_id`, `price_type`, and `limit_points_per_bookmaker` to keep responses small.
- Store history separately from live caches because it is an audit/backtesting view, not the current tradable price. Plan a historical odds integration →
Failure modes
400 Fix invalid filters, cursors, timestamps, or request shape.
401 API key is missing or invalid. Rotate or reconfigure the key.
403 The key is valid but lacks the plan, product, bookmaker, stream, racing, or strategy access.
404 The event, race, result, or selection is not available in the current public surface.
429 Back off, honor `Retry-After`, check `/usage`, and reduce request volume.
5xx Retry with backoff and keep the last good cached data marked with its timestamp.
Stream close Reconnect with `since`; reload the snapshot if the stream sends `resync`.
Empty or stale data Show unavailable/stale state instead of treating missing odds as valid prices.
Endpoint group
Start here
API identity, base URL, authentication, and reference links.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET API metadata /v1/
Returns the API name, version, OpenAPI document URL, and hosted reference URL.
Public endpoint Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"name": "Odds API",
"version": "1.0.0",
"openapi": "/v1/openapi.json",
"reference": "/v1/reference"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Status
Buyer-facing API availability, latency, stream health, and rate-limit health.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Public health summary /v1/status
Returns a sanitized public status summary for buyer-facing pages. The response includes recent component availability, latency percentiles, 5xx error rate, stream health, and rate-limit health without exposing internal service names, infrastructure metrics, bookmaker details, raw traffic volume, or incident history.
Public endpoint Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/status"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
API status: Public health summary
{
"status": "operational",
"as_of": "2026-04-29T10:25:00Z",
"window_seconds": 300,
"components": [
{
"id": "rest_api",
"name": "REST API",
"status": "operational",
"metrics": {
"uptime_pct": 100.0,
"p50_ms": 24.0,
"p95_ms": 410.0,
"p99_ms": 846.0,
"error_rate_pct": 0.02
}
}
],
"rate_limits": {
"status": "operational",
"throttled_pct": 0.4
},
"source": {
"fresh": true,
"age_seconds": 18
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Account
Current API identity, usage counters, and contract limits.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Current identity /v1/me
Returns the authenticated API identity and enabled product capabilities for the supplied key.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/me"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"method": "api_key",
"client_id": "string",
"capabilities": {},
"membership_tier": 123
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Usage /v1/usage
Returns quota and usage counters for the supplied API key. New odds-api.net pricing uses API credits rather than raw request counts. Production clients should check this endpoint when 429 responses persist so quota exhaustion does not become an infinite retry loop.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/usage"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Account: Usage
{
"period_start_utc": "2026-05-01T00:00:00Z",
"period_end_utc": "2026-06-01T00:00:00Z",
"plan": "live",
"pricing_model": "odds_api_net_v2",
"api_credits_used": 18420,
"api_credits_limit": 20000000,
"stream_hours_used": 438.25,
"stream_hours_limit": 6000,
"stream_logical_bytes_used": 187654321,
"stream_logical_bytes_limit": 536870912000,
"stream_concurrent_units_used": 7,
"stream_concurrent_units_limit": 25,
"exceeded": false
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Limits /v1/limits
Returns contract-level API-credit, request, stream, add-on, and response limits that clients should respect, plus a `bets` block stating whether betting-opportunity feeds are on for the key and with which strategies and bookmakers. Use this to cap page sizes, snapshot sizes, stream heartbeat settings, and stream batch sizes before starting high-volume jobs.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/limits"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Account: Limits
{
"responses": {
"events_limit_max": 1000,
"odds_snapshot_limit_max": 25000,
"bets_snapshot_limit_max": 20000
},
"sse": {
"heartbeat_sec_min": 5,
"heartbeat_sec_max": 120,
"max_batch_default": 500
},
"streams": {
"metering": "all authenticated API-key SSE and WebSocket connections",
"formula": "stream_units * open_seconds / 3600",
"enforcement_interval_seconds": 5
},
"bets": {
"enabled": true,
"strategies": [
"pos_ev",
"arbitrage"
],
"bookmakers": [
"bet365",
"pinnacle"
]
},
"add_ons": {
"bets_access": false
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Catalog
Supported sports, leagues, bookmakers, and approximate market coverage.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Sports /v1/sports
Lists sports with event and odds coverage.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/sports"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"items": [
"string"
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Leagues /v1/leagues
Lists available leagues. Pass `sport` to narrow the response.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/leagues?sport=basketball"
Parameters
Query
sport
string
Sport filter. Use `/sports` to discover supported values.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"items": [
"string"
],
"details": [
{
"name": "Saudi Pro League",
"sport": "soccer",
"country_code": "SA",
"country": "Saudi Arabia"
}
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Bookmakers /v1/bookmakers
Lists active bookmakers accepted by bookmaker filters across odds and betting endpoints. Each item includes the country codes where that bookmaker is available. Pass `country_code=AU` or `country_code=AU,UK` to filter the catalog.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/bookmakers"
Parameters
Query
country_code
string
Comma-separated country code filter, for example `AU` or `AU,UK`.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Catalog: Bookmakers
{
"items": [
{
"bookmaker": "bet365",
"country_codes": [
"AU",
"UK"
]
},
{
"bookmaker": "pinnacle",
"country_codes": [
"US"
]
}
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Bookmaker countries /v1/bookmakers/countries
Lists country codes represented in the active bookmaker catalog and the bookmakers available in each country.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/bookmakers/countries"
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Catalog: Bookmaker countries
{
"items": [
{
"country_code": "AU",
"country": "Australia",
"bookmakers": [
"bet365",
"sportsbet"
]
},
{
"country_code": "UK",
"country": "United Kingdom",
"bookmakers": [
"bet365"
]
}
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Coverage /v1/coverage
Returns public bookmaker, sport, league, and recently observed market coverage. Market records are approximate and based on normalized odds lines seen in the configured lookback window, not a guarantee that every market is available for every event at request time.
Public endpoint Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/coverage?sport=basketball&league=NBA"
Parameters
Query
bookmaker
string
Canonical bookmaker filter. Use `/bookmakers` or `/coverage` to discover supported keys.
sport
string
Sport filter. Use `/sports` to discover supported values.
league
string
League filter. Use `/leagues?sport=...` to discover supported values.
country_code
string
Comma-separated country code filter, for example `AU` or `AU,UK`.
lookback_days
integer
Number of days of recently observed approximate market coverage to include. Maximum is 90.
view
string
`summary` returns the bookmaker, sport and league catalog without market rows (small and cacheable; use it for counts and pickers). `full` (default) also returns every observed market row.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Catalog: Coverage
{
"as_of": "2026-04-29T10:25:00Z",
"bookmakers": [
{
"bookmaker": "bet365",
"country_codes": [
"AU",
"UK"
]
},
{
"bookmaker": "sportsbet",
"country_codes": [
"AU"
]
}
],
"sports": [
"basketball",
"rugby league"
],
"leagues": [
{
"sport": "basketball",
"league": "NBA"
},
{
"sport": "rugby league",
"league": "NRL"
}
],
"markets": [
{
"bookmaker": "bet365",
"sport": "basketball",
"league": "NBA",
"bet_type": "moneyline",
"last_seen_at": "2026-04-29T10:20:00Z",
"sample_event_id": "3704597661"
},
{
"bookmaker": "sportsbet",
"sport": "rugby league",
"league": "NRL",
"bet_type": "total",
"metric": "tries",
"last_seen_at": "2026-04-29T10:18:00Z",
"sample_event_id": "3704597662"
}
],
"source": {
"markets_are_approximate": true,
"lookback_days": 30
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Widgets
Public-safe embeddable widget feeds for approved API clients.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Odds ticker /v1/widgets/odds-ticker
Returns a small public-safe odds ticker payload for an embeddable website widget. The response is projected from the same Redis-backed main-line sports odds used by the API. Rolling league requests return upcoming events. An exact `event_id` returns current odds; `include_completed=true` also permits display of a confirmed finished event's retained final usable capture. Exact-event responses add event identity, lifecycle and capture metadata. Missing captures return an explicit empty result. Cancelled/postponed events do not return archived prices. This grants no general odds-history access. The payload omits raw payloads, private source metadata, links, no-vig prices, fair odds, debug IDs, and team logo metadata. API keys marked `widgets_only=true` can access this route plus account routes only.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/widgets/odds-ticker?league=NBA&bookmakers=bet365&widget_id=string&limit=25"
Parameters
Query
league required
string
League filter. Use `/leagues?sport=...` to discover supported values.
bookmakers required
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
widget_id required
string
Stable widget identifier configured on the API client record.
markets
string
Comma-separated widget market list. Supported values are moneyline, handicap, and total; aliases include h2h, 1x2, spread, and over_under.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
window_hours
integer
event_id
string
Canonical event or race identifier from an event list response.
include_completed
boolean
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Widgets: Odds ticker
{
"league": "EPL",
"widget_id": "homepage-ticker",
"last_updated": "2026-07-09T01:02:03Z",
"events": [
{
"league": "EPL",
"event_name": "Arsenal vs Chelsea",
"start_time": 1783558800,
"last_updated": "2026-07-09T01:02:03Z",
"markets": [
{
"market": "moneyline 3w",
"bookmakers": [
{
"label": "tab",
"selections": [
{
"selection": "home",
"price": 2.2
},
{
"selection": "away",
"price": 2.9
},
{
"selection": "draw",
"price": 3.4
}
]
}
]
}
]
}
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Sports events
Upcoming and live sports events plus event metadata.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Search /v1/events
Searches sports events by sport, league, team, time window, status, bookmaker coverage, and pagination cursor. For production polling, use bounded time windows, keep filters stable across pages, and pass `next_cursor` back as `cursor` until there is no next cursor. For live discovery start with `/v1/events/live`; `event_states=in_play` returns only events with a fresh live observation and adds a `hint` when started but unconfirmed events were excluded. Every item has a plain `live_status`.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events?sport=basketball&league=NBA&limit=25"
Parameters
Query
sport
string
Sport filter. Use `/sports` to discover supported values.
league
string
League filter. Use `/leagues?sport=...` to discover supported values.
start_from
integer
Unix seconds lower bound for event start time. Use bounded windows in production polling.
start_to
integer
Unix seconds upper bound for event start time. Keep windows narrow for hot sync jobs.
cursor
string
Pagination cursor from the previous `next_cursor`. Keep filters identical between pages.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
include_bookmaker_ids
boolean
When true, include bookmaker-to-odds-data IDs and preview ID maps on event responses.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_opportunity_counts
boolean
not_started_only
boolean
not_started_buffer_seconds
integer
event_states
string
Lifecycle filter. Requesting in_play automatically applies the live lookback window.
live_candidates
boolean
Include already-started events that remain candidates for live play; this is not confirmation of current play.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Sports events: Search
{
"items": [
{
"event_id": "3704597661",
"sport": "rugby-league",
"league": "NRL",
"start_time": 1760000000,
"home_team": "Home",
"away_team": "Away",
"bookmakers": {
"bet365": "odds-doc-id"
}
}
],
"next_cursor": null,
"count": 1
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET GET events live /v1/events/live
Public Odds API operation. Authenticate with `X-API-Key`. Check timestamps before displaying prices and handle empty, stale, or suspended markets.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/live?sport=basketball&league=NBA&limit=25"
Parameters
Query
sport
string
Sport filter. Use `/sports` to discover supported values.
league
string
League filter. Use `/leagues?sport=...` to discover supported values.
cursor
string
Pagination cursor from the previous `next_cursor`. Keep filters identical between pages.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
include_bookmaker_ids
boolean
When true, include bookmaker-to-odds-data IDs and preview ID maps on event responses.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_opportunity_counts
boolean
confirmed
boolean
Only events with a fresh live observation (live_status=live); same as /v1/events?event_states=in_play.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"items": [
{
"event_id": "3704597661",
"sport": "basketball",
"league": "NBA",
"start_time": 123,
"home_team": "string",
"away_team": "string",
"event_state": "string",
"event_state_certainty": "string",
"event_state_source": "string",
"state_observed_at": 123
}
],
"next_cursor": "string",
"count": 123,
"hint": {
"code": "string",
"message": "string",
"count": 0,
"see": "string"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Event details /v1/events/{event_id}
Returns the current event record for a canonical sports event ID.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_bookmaker_ids
boolean
When true, include bookmaker-to-odds-data IDs and preview ID maps on event responses.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"event_id": "3704597661",
"data": {}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Bookmaker coverage /v1/events/{event_id}/bookmakers
Lists bookmakers currently attached to a sports event.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/bookmakers"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"event_id": "3704597661",
"items": [
"string"
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Sports odds
Sports odds snapshots, line movement, Server-Sent Events, and WebSocket updates.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Snapshot /v1/events/{event_id}/fair-odds
Public Odds API operation. Authenticate with `X-API-Key`. Check timestamps before displaying prices and handle empty, stale, or suspended markets.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/fair-odds?limit=25"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
selection_id
string
selection_key
string
Stable selection identifier from an odds snapshot line, used for history and line movement.
market_group_id
string
Optional market grouping filter for history queries.
bet_type
string
metric
string
period
integer
period_str
string
line
string
player_name
string
team_subject
string
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
cursor
string
Pagination cursor from the previous `next_cursor`. Keep filters identical between pages.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"event_id": "3704597661",
"schema_version": "fair-prices.v1",
"snapshot_id": "string",
"input_revision": 123,
"reference_policy": "all_eligible_reference_books",
"items": [
{
"selection_id": "string",
"bet_type": "string",
"market_family": "string",
"period": "0",
"period_str": "string",
"metric": "string",
"line": "string",
"player_name": "string",
"team_subject": "string",
"selection_keys": [
"string"
]
}
],
"next_cursor": "string",
"complete": true
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Snapshot /v1/events/{event_id}/odds/snapshot
Returns the current odds lines for one event. Use filters to narrow bookmakers, market types, market keys, periods, and metrics (for example `metrics=corners,cards`). An explicit `bookmakers` filter returns every matching line for those bookmakers in one response, up to the 25,000-item safety cap. Without a bookmaker filter, pages contain whole bookmakers, so a bookmaker's matching markets are never split across pages. Follow the opaque `next_cursor` until `complete=true`. Cache by request shape. `as_of_ts_ms` is event-wide: the latest acceptance from any bookmaker on the event, including bookmakers this response does not return, so it can look fresh while the bookmakers you asked for are old. Use `bookmaker_as_of_ts_ms` for bookmaker-specific freshness and compare it with `target_refresh_interval_seconds`; `oldest_bookmaker_as_of_ts_ms`, `newest_bookmaker_as_of_ts_ms` and `stale_bookmakers` (returned bookmakers last accepted more than twice the target interval for the event's current kickoff band ago) summarise it (prediction markets report when their current contract prices were accepted). Respect `ttl_seconds` when present, and persist `resume` when you plan to subscribe to updates. Pass `price_fields=odds,fair` to include nullable composite fair odds alongside bookmaker odds. Exchange orderbooks are excluded from this sportsbook-style odds surface.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/odds/snapshot?limit=25&bookmakers=bet365&types=moneyline&market_keys=moneyline"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
limit
integer
Soft item target when `bookmakers` is omitted. Pages contain whole bookmakers and may exceed this target. With an explicit bookmaker filter, all matching lines are returned up to the 25,000-item safety cap.
cursor
string
Opaque bookmaker-page cursor from the previous `next_cursor`. Use only when `bookmakers` is omitted and keep all filters identical between pages.
bookmakers
string
Comma-separated bookmaker allow-list. Explicitly requested bookmakers are returned complete in one response, up to the 25,000-item safety cap. Use `/bookmakers` to discover supported keys. Requested keys this API key cannot access, or that are not bookmakers, are listed in `excluded_bookmakers` and the `X-Excluded-Bookmakers` header.
types
string
Comma-separated market type allow-list for odds filters, for example `moneyline,total`. An unrecognised value matches no lines; the event odds snapshot then lists it in `warnings` with the closest accepted spellings.
market_keys
string
Comma-separated market key allow-list for odds filters.
periods
string
Comma-separated period allow-list for odds filters. Each value matches a line's numeric `period` or its period label, for example `full time`, `1st half` or `after 15 minutes`. Numeric `0` also matches timed checkpoints such as `after 15 minutes`; use `full time` to select only full-time lines. An unrecognised value matches no lines; the event odds snapshot then lists it in `warnings`.
metrics
string
Comma-separated metric allow-list for odds filters, matched case-insensitively against each line's `metric`, for example `corners,cards`. Main markets are `standard`; some sources label soccer main markets `goals` instead, so request `standard,goals` to get both. An unrecognised value (for example `points`) matches no lines; the event odds snapshot then lists it in `warnings` with the closest accepted spellings.
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
include_stale
boolean
Return bookmakers whose prices are very stale (last accepted more than max(24 h, 20 x target_refresh_interval_seconds, the target for the event's current kickoff band) ago, or only pre-match prices after kickoff). By default they are left out and listed in excluded_bookmakers with reason `stale`.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
X-Excluded-Bookmakers
string
Present when the `bookmakers` filter named bookmakers this response cannot contain: comma-separated `key:reason` pairs, where reason is `not_entitled` (not included in this API key's plan or bookmaker grant) or `unknown_bookmaker` (not a key from `/bookmakers`).
Event odds: Snapshot
{
"event_id": "3704597661",
"as_of_ts_ms": 1760000000000,
"snapshot_capture_ts_ms": 1759999999800,
"bookmaker_as_of_ts_ms": {
"bet365": 1760000000000
},
"oldest_bookmaker_as_of_ts_ms": 1760000000000,
"newest_bookmaker_as_of_ts_ms": 1760000000000,
"stale_bookmakers": [],
"target_refresh_interval_seconds": 60,
"ttl_seconds": 1800,
"items": [
{
"id": "bet365::moneyline::moneyline::0::::home::",
"event_id": "3704597661",
"bookmaker": "bet365",
"market_key": "moneyline",
"bet_type": "moneyline",
"period": "full time",
"side": "home",
"selection_name": "Home",
"odds": 2.1,
"fair_odds": 1.98,
"is_available": true
}
],
"next_cursor": null,
"complete": true,
"bookmakers_included": [
"bet365"
],
"bookmaker_counts": {
"bet365": 1
},
"resume": "1760000000000-0"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
413 The requested bookmaker-complete snapshot exceeds the response safety cap.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/events/{event_id}/odds/stream
Server-Sent Events feed for odds changes on one event. Subscribe after reading the snapshot and pass the snapshot `resume` value as `since` to receive catch-up changes when available. Handle ordered semantic `delta` batches idempotently and persist each batch's `resume`; a `heartbeat` carries current freshness even when prices did not change. Reload the snapshot after `resync`. Exchange orderbook changes are served only from the exchange orderbook stream.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/odds/stream?bookmakers=bet365&types=moneyline&market_keys=moneyline&since=1760000000000-0"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys. Requested keys this API key cannot access, or that are not bookmakers, are reported in the `X-Excluded-Bookmakers` header.
types
string
Comma-separated market type allow-list for odds filters, for example `moneyline,total`. An unrecognised value matches no lines; the event odds snapshot then lists it in `warnings` with the closest accepted spellings.
market_keys
string
Comma-separated market key allow-list for odds filters.
periods
string
Comma-separated period allow-list for odds filters. Each value matches a line's numeric `period` or its period label, for example `full time`, `1st half` or `after 15 minutes`. Numeric `0` also matches timed checkpoints such as `after 15 minutes`; use `full time` to select only full-time lines. An unrecognised value matches no lines; the event odds snapshot then lists it in `warnings`.
metrics
string
Comma-separated metric allow-list for odds filters, matched case-insensitively against each line's `metric`, for example `corners,cards`. Main markets are `standard`; some sources label soccer main markets `goals` instead, so request `standard,goals` to get both. An unrecognised value (for example `points`) matches no lines; the event odds snapshot then lists it in `warnings` with the closest accepted spellings.
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
X-Excluded-Bookmakers
string
Present when the `bookmakers` filter named bookmakers this response cannot contain: comma-separated `key:reason` pairs, where reason is `not_entitled` (not included in this API key's plan or bookmaker grant) or `unknown_bookmaker` (not a key from `/bookmakers`).
Decoded delta message
event: delta
data: {
"event_id": "3704597661",
"resume": "1760000000000-0",
"snapshot_id": "capture-123:3704597661",
"batch_index": 1,
"batch_count": 1,
"changes": []
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/events/{event_id}/odds/ws
WebSocket feed for odds changes on one event. Messages use the same `delta`, `heartbeat`, and `resync` payloads as the SSE stream. Reconnect with jittered exponential backoff and `since=<last_resume>`.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/events/3704597661/odds/ws?bookmakers=bet365&types=moneyline&market_keys=moneyline&since=1760000000000-0&api_key=$ODDS_API_KEY"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
types
string
Comma-separated market type allow-list for odds filters, for example `moneyline,total`. An unrecognised value matches no lines; the event odds snapshot then lists it in `warnings` with the closest accepted spellings.
market_keys
string
Comma-separated market key allow-list for odds filters.
periods
string
Comma-separated period allow-list for odds filters. Each value matches a line's numeric `period` or its period label, for example `full time`, `1st half` or `after 15 minutes`. Numeric `0` also matches timed checkpoints such as `after 15 minutes`; use `full time` to select only full-time lines. An unrecognised value matches no lines; the event odds snapshot then lists it in `warnings`.
metrics
string
Comma-separated metric allow-list for odds filters, matched case-insensitively against each line's `metric`, for example `corners,cards`. Main markets are `standard`; some sources label soccer main markets `goals` instead, so request `standard,goals` to get both. An unrecognised value (for example `points`) matches no lines; the event odds snapshot then lists it in `warnings` with the closest accepted spellings.
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"resume": "1760000000000-0",
"snapshot_id": "capture-123:3704597661",
"batch_index": 1,
"batch_count": 1,
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"resume": "1760000000000-0",
"snapshot_id": "capture-123:3704597661",
"batch_index": 1,
"batch_count": 1,
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Snapshot /v1/events/{event_id}/odds/history
Returns line movement for a single selection across bookmakers and a time range. Use `selection_key` from an odds snapshot response, bound queries with `from_ts` and `to_ts`, and narrow by bookmaker or market when building charts or backtests.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/odds/history?selection_key=moneyline%3Ahome&bookmakers=bet365"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
selection_key required
string
Stable selection identifier from an odds snapshot line, used for history and line movement.
market_group_id
string
Optional market grouping filter for history queries.
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys. Requested keys this API key cannot access, or that are not bookmakers, are reported in the `X-Excluded-Bookmakers` header.
from_ts
string
ISO8601 UTC start timestamp for a bounded history query.
to_ts
string
ISO8601 UTC end timestamp for a bounded history query.
price_type
string
History price type to return, for example odds.
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
limit_points_per_bookmaker
integer
Maximum history points per bookmaker. Use this to keep chart/backtest payloads bounded.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
X-Excluded-Bookmakers
string
Present when the `bookmakers` filter named bookmakers this response cannot contain: comma-separated `key:reason` pairs, where reason is `not_entitled` (not included in this API key's plan or bookmaker grant) or `unknown_bookmaker` (not a key from `/bookmakers`).
Event odds history: Snapshot
{
"event_id": "3704597661",
"selection_key": "moneyline:home",
"price_type": "odds",
"series": [
{
"bookmaker_name": "bet365",
"points": [
{
"tick_ts": "2026-04-29T08:00:00Z",
"is_available": true,
"odds": 2.08
},
{
"tick_ts": "2026-04-29T08:05:00Z",
"is_available": true,
"odds": 2.1
}
]
}
],
"meta": {
"from_ts": "2026-04-29T08:00:00Z",
"to_ts": "2026-04-29T09:00:00Z",
"available_price_types": [
"odds",
"odds_no_vig",
"fair_odds"
]
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/events/{event_id}/odds/history/stream
Server-Sent Events feed for line movement on one selection. This is useful for charts that should update while an event market is moving.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/odds/history/stream?selection_key=moneyline%3Ahome&bookmakers=bet365&since=1760000000000-0&catchup=true"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
selection_key required
string
Stable selection identifier from an odds snapshot line, used for history and line movement.
market_group_id
string
Optional market grouping filter for history queries.
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys. Requested keys this API key cannot access, or that are not bookmakers, are reported in the `X-Excluded-Bookmakers` header.
price_type
string
History price type to return, for example odds.
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
X-Excluded-Bookmakers
string
Present when the `bookmakers` filter named bookmakers this response cannot contain: comma-separated `key:reason` pairs, where reason is `not_entitled` (not included in this API key's plan or bookmaker grant) or `unknown_bookmaker` (not a key from `/bookmakers`).
Decoded delta message
event: delta
data: {
"event_id": "3704597661",
"selection_key": "moneyline:home",
"resume": "1760000000000-0",
"points": []
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/events/{event_id}/odds/history/ws
WebSocket feed for line movement on one selection. Messages mirror the history SSE stream payloads.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/events/3704597661/odds/history/ws?selection_key=moneyline%3Ahome&bookmakers=bet365&since=1760000000000-0&catchup=true&api_key=$ODDS_API_KEY"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
selection_key required
string
Stable selection identifier from an odds snapshot line, used for history and line movement.
market_group_id
string
Optional market grouping filter for history queries.
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
price_type
string
History price type to return, for example odds.
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"selection_key": "moneyline:home",
"resume": "1760000000000-0",
"points": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"selection_key": "moneyline:home",
"resume": "1760000000000-0",
"points": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Past events (beta) /v1/history/events
Beta. Lists finished events that odds history holds, by UTC start date, for backtesting fixtures that have left `/v1/events` (about a day after they finish). Filter with `sport` and `league`, where `league` is the league name exactly as `/v1/events` returns it (for example `Colombian Primera A`; case-insensitive, not an ID). One request spans at most 8 days (`date_from` to `date_to`, inclusive) and stays within the plan's history lookback. Use each `event_id` with the selection catalogue, then its `selection_key` values with the history endpoint. Requires the history add-on (403 `history_addon_required` without it).
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/history/events?date_from=string&sport=basketball&league=NBA&limit=25"
Parameters
Query
date_from required
string
First UTC start date, YYYY-MM-DD
date_to
string
Last UTC start date (inclusive); defaults to date_from
sport
string
Sport filter. Use `/sports` to discover supported values.
league
string
League filter. Use `/leagues?sport=...` to discover supported values.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
Responses
200 Successful Response
application/json · value
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
string
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Selection catalogue (beta) /v1/events/{event_id}/odds/history/selections
Beta. Lists the selection keys that odds history holds for one event, including finished events whose odds snapshot is already empty. Use each `selection_key` with the history endpoint. Main-line selections are listed shortly after kickoff; all recorded markets, including player props, are listed once the UTC day of their last price change has been processed (usually by 03:00 UTC the next day). Requires the history add-on.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/odds/history/selections?bookmakers=bet365"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
bet_types
string
Comma-separated bet types, e.g. `player prop`
Responses
200 Successful Response
application/json · value
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Event odds history: Selection catalogue (beta)
{
"event_id": "3704597661",
"event": {
"sport": "soccer",
"league": "EPL",
"start_time": "2026-10-11T14:30:00Z"
},
"items": [
{
"selection_key": "b73d7d0a7173d212d4c30b33e7f8d396e665db00",
"market_group_id": "8f95b02f0249d018439f797c3cc4562cc0a3aa2b",
"market_key": null,
"bet_type": "player prop",
"period": "full time",
"metric": "player goals",
"side": null,
"line": "0.5",
"player_name": "example player",
"selection_name": "Example Player",
"bookmakers": [
"bet365",
"sportsbet"
],
"first_tick_ts": "2026-10-09T06:12:40Z",
"last_tick_ts": "2026-10-11T14:29:51Z",
"sources": [
"ticks"
]
}
],
"meta": {
"count": 1,
"tick_catalogue_updated_at": "2026-10-12T03:20:11Z",
"final_capture": true
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Sports exchange
Sports betting exchange order books with back/lay ladders, liquidity, and live updates.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Snapshot /v1/events/{event_id}/exchange/orderbook/snapshot
Returns sports betting exchange order books for one event. Supported exchanges are betfair, smarkets, and matchbook. Each selection includes back and lay price levels with available size, plus top-of-book summary fields such as best_back_price and best_lay_price. Market identity, team identity, source and observation timestamps, currency, total matched, total available, traded volume, and traded volume by price are retained when supplied by the exchange source. Smarkets volume is reported in GBP and includes its native double_stake_volume when available. Use `depth` to limit executable ladder levels and cache only briefly because exchange liquidity can move quickly. Betfair books show real resting orders; API keys approved for virtual prices can pass price_view=virtual for Betfair's displayed ladder, which includes cross-matched prices, with sizes in GBP.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/exchange/orderbook/snapshot?market_keys=moneyline"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
exchanges
string
Comma-separated exchange allow-list. Supported values are `betfair`, `smarkets`, and `matchbook`.
market_keys
string
Comma-separated market key allow-list for odds filters.
selection_keys
string
Comma-separated stable selection identifiers from an exchange order book or odds snapshot.
depth
integer
Number of exchange price levels per back/lay side. Exchanges currently supply at most 3 levels per side, so values above 3 return the levels available. Use smaller values for lower latency and payload size.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
refresh
boolean
Request bounded, demand-driven Betfair collection before returning.
refresh_timeout_seconds
number
price_view
string
Betfair ladder to return. Omit for the default book. standard: real resting orders only (the default book, labelled). virtual: Betfair's displayed ladder including cross-matched virtual prices, as on the Betfair website; Betfair books only, opt-in per API key. Labelled responses carry price_view.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Event exchange order book: Snapshot
{
"event_id": "3704597661",
"as_of_ts_ms": 1760000000000,
"ttl_seconds": 30,
"items": [
{
"id": "betfair::1.23456789::moneyline",
"event_id": "3704597661",
"exchange": "betfair",
"exchange_market_id": "1.23456789",
"market_key": "moneyline",
"market_name": "Match Odds",
"bet_type": "moneyline",
"period": "full time",
"home_team": "Home",
"away_team": "Away",
"status": "open",
"in_play": false,
"total_matched": 24567.12,
"total_available": 204.8,
"total_available_source": "displayed_ladders",
"currency": "AUD",
"observed_at": "2026-08-22T08:00:00Z",
"selections": [
{
"selection_key": "moneyline:home",
"exchange_selection_id": "12345",
"selection_name": "Home",
"last_traded_price": 2.08,
"traded_volume_by_price": [
{
"price": 2.08,
"size": 300.0
}
],
"available_to_back": [
{
"price": 2.08,
"size": 120.5
}
],
"available_to_lay": [
{
"price": 2.1,
"size": 84.3
}
],
"best_back_price": 2.08,
"best_back_size": 120.5,
"best_lay_price": 2.1,
"best_lay_size": 84.3
}
]
}
],
"next_cursor": null,
"resume": "1760000000000-0"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/events/{event_id}/exchange/orderbook/stream
Server-Sent Events feed for sports exchange order book changes on one event. Subscribe after reading the snapshot and pass the snapshot `resume` value as `since` to receive catch-up changes when available. Handle `delta`, `heartbeat`, and `resync`; reload the snapshot after `resync`.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/exchange/orderbook/stream?market_keys=moneyline&since=1760000000000-0&catchup=true"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
exchanges
string
Comma-separated exchange allow-list. Supported values are `betfair`, `smarkets`, and `matchbook`.
market_keys
string
Comma-separated market key allow-list for odds filters.
selection_keys
string
Comma-separated stable selection identifiers from an exchange order book or odds snapshot.
depth
integer
Number of exchange price levels per back/lay side. Exchanges currently supply at most 3 levels per side, so values above 3 return the levels available. Use smaller values for lower latency and payload size.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
price_view
string
Betfair ladder to return. Omit for the default book. standard: real resting orders only (the default book, labelled). virtual: Betfair's displayed ladder including cross-matched virtual prices, as on the Betfair website; Betfair books only, opt-in per API key. Labelled responses carry price_view.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Decoded delta message
event: delta
data: {
"event_id": "3704597661",
"resume": "1760000000000-0",
"changes": []
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/events/{event_id}/exchange/orderbook/ws
WebSocket feed for sports exchange order book changes on one event. Messages mirror the exchange order book SSE stream payloads.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/events/3704597661/exchange/orderbook/ws?market_keys=moneyline&since=1760000000000-0&catchup=true&api_key=$ODDS_API_KEY"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
exchanges
string
Comma-separated exchange allow-list. Supported values are `betfair`, `smarkets`, and `matchbook`.
market_keys
string
Comma-separated market key allow-list for odds filters.
selection_keys
string
Comma-separated stable selection identifiers from an exchange order book or odds snapshot.
depth
integer
Number of exchange price levels per back/lay side. Exchanges currently supply at most 3 levels per side, so values above 3 return the levels available. Use smaller values for lower latency and payload size.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
price_view
string
Betfair ladder to return. Omit for the default book. standard: real resting orders only (the default book, labelled). virtual: Betfair's displayed ladder including cross-matched virtual prices, as on the Betfair website; Betfair books only, opt-in per API key. Labelled responses carry price_view.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"resume": "1760000000000-0",
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"resume": "1760000000000-0",
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Discover markets /v1/events/{event_id}/exchange/markets
Lists available Betfair markets across sports, including soccer and cricket. Supply an odds-api event ID (the default id_type) or id_type=betfair with a native Betfair event ID. Filter using market_types; MATCH_ODDS is sorted first. Use the returned opaque market_id values with the multiplexed WebSocket; do not send Betfair market names or IDs.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/exchange/markets"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
exchange
string
id_type
string
Namespace of event_id: the default for an odds-api event ID, or betfair for a numeric Betfair event ID (not a market ID).
market_types
string
Optional comma-separated Betfair market types, e.g. MATCH_ODDS,OVER_UNDER_25.
refresh
boolean
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"score_subscription": {
"websocket_url": "string",
"command": {},
"max_events_per_connection": 123
},
"event_id": "3704597661",
"exchange": "string",
"count": 123,
"available_market_types": [
"string"
],
"markets": [
{
"market_id": "string",
"event_id": "3704597661",
"wagerwise_event_id": "3704597661",
"betfair_event_id": "3704597661",
"exchange": "string",
"sport": "basketball",
"market_key": "moneyline",
"bet_type": "string",
"metric": "string",
"period": "0"
}
],
"subscription": {
"websocket_url": "string",
"command": {},
"max_markets_per_connection": 123
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET List in-play Betfair events /v1/exchange/betfair/events
Lists every event Betfair reports in play, including native-only events outside the odds-api event schedule. Each item has an opaque match_odds_market_id you can subscribe to on the multiplexed WebSocket without a discovery call; use markets_url for other markets. Filter with sport and scheduled. Refreshed about every 30 seconds; source_age_seconds and stale report freshness.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/exchange/betfair/events?sport=basketball&limit=25"
Parameters
Query
in_play
boolean
Only true is supported: events Betfair reports in play now.
sport
string
Sport filter. Use `/sports` to discover supported values.
scheduled
boolean
true: only events in the odds-api event schedule; false: only native-only Betfair events.
offset
integer
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"exchange": "betfair",
"items": [
{
"betfair_event_id": "3704597661",
"event_id": "3704597661",
"wagerwise_event_id": "3704597661",
"sport": "basketball",
"event_name": "string",
"competition_name": "string",
"start_time": "string",
"in_play": true,
"match_odds_market_id": "string",
"runners": [
"string"
]
}
],
"count": 123,
"total": 123,
"observed_at": 123,
"source_age_seconds": 123,
"stale": true,
"subscription": {
"websocket_url": "string",
"command": {},
"max_markets_per_connection": 123
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Discover by Betfair event ID /v1/exchange/betfair/events/{betfair_event_id}/markets
Public Odds API operation. Authenticate with `X-API-Key`. Check timestamps before displaying prices and handle empty, stale, or suspended markets.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/exchange/betfair/events/3704597661/markets"
Parameters
Path
betfair_event_id required
string
Query
market_types
string
refresh
boolean
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"score_subscription": {
"websocket_url": "string",
"command": {},
"max_events_per_connection": 123
},
"event_id": "3704597661",
"exchange": "string",
"count": 123,
"available_market_types": [
"string"
],
"markets": [
{
"market_id": "string",
"event_id": "3704597661",
"wagerwise_event_id": "3704597661",
"betfair_event_id": "3704597661",
"exchange": "string",
"sport": "basketball",
"market_key": "moneyline",
"bet_type": "string",
"metric": "string",
"period": "0"
}
],
"subscription": {
"websocket_url": "string",
"command": {},
"max_markets_per_connection": 123
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Multiplexed WebSocket /v1/exchange/orderbooks/ws
One support-approved WebSocket can subscribe and unsubscribe dynamically from up to five opaque market IDs. Send {op: subscribe, market_ids: [...], depth: 3}; the server acknowledges immediately. If the API holds a last-known book it is sent at once as an image with origin=cache: it can be of any age, so check freshness and source_ts. The live stream's book follows, usually within a few seconds, as an image with origin=live (cold market) or as a delta. source_ts is Betfair's publish time of the last change, observed_at is the API's ingest time, and source_delayed reports Betfair delayed (180 s+ conflation) or latent data, not age. Heartbeats every 5 s carry a sync map per subscribed market: in_sync=true means the live Betfair stream confirmed within the last 15 s that the delivered book has no newer change, so an unchanged price is current. Every order book includes in_play, synced_at and in_sync. The handshake uses one API credit; connection time and logical bytes use the plan's stream quotas. Connect with?price_view=virtual (API keys approved for virtual prices) to receive Betfair's displayed ladder, including cross-matched prices with sizes in GBP; image and delta messages then carry price_view. Without the parameter the feed shows real resting orders only.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/exchange/orderbooks/ws?api_key=$ODDS_API_KEY"
Parameters
Query
price_view
enum: standard, virtual
Betfair ladder to return. Omit for the default book. standard: real resting orders only (the default book, labelled). virtual: Betfair's displayed ladder including cross-matched virtual prices, as on the Betfair website; Betfair books only, opt-in per API key. Labelled responses carry price_view.
Responses
101 WebSocket connection established. Send subscribe/unsubscribe JSON commands.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"type": "subscribed",
"event_id": "3704597661",
"resume": "1760000000000-0",
"origin": "cache",
"market_ids": [
"string"
],
"changes": [
{}
],
"sync": {
"key": {
"synced_at": "string",
"sync_age_seconds": 1.23,
"in_sync": true
}
},
"price_view": "standard"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Multiplexed WebSocket /v1/exchange/tennis/scores/ws
Requires X-API-Key with tennis_scores_enabled=true. Discover tennis event IDs first using exchange market discovery. Send subscribe/unsubscribe commands with event_ids (maximum 10), or ping. Opening alone starts no collection. The first score is an image; delta contains a complete replacement score. Five-second heartbeats indicate socket liveness only. Scores are ephemeral: no history or replay. received_at is our receipt time; source_timestamp is null. Scores and prices are independent observations and may be delayed or inaccurate. Nullable fields are not inferred. Handle unknown_event_ids, event_limit_exceeded, warming_timeout, score_unavailable, stale and upstream_unavailable. Quota exhaustion closes with 4429; authentication and availability use the standard stream close codes. Reconnect and subscribe again after disconnect; sequence numbers are scoped to the active router process.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/exchange/tennis/scores/ws?api_key=$ODDS_API_KEY"
Responses
101 WebSocket established; subscribe to discovered tennis event IDs.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"type": "image",
"event_id": "3704597661",
"stream_id": "string",
"sequence": 123,
"update_kind": "initial",
"score": {
"sport": "basketball",
"provider": "string",
"home": {
"name": "string",
"sets": 123,
"games": 123,
"points": "string",
"is_serving": true,
"game_sequence": [
123
]
},
"away": {
"name": "string",
"sets": 123,
"games": 123,
"points": "string",
"is_serving": true,
"game_sequence": [
123
]
},
"current_set": 123,
"current_game": 123,
"match_status": "string",
"tie_break": true,
"received_at": "string",
"source_timestamp": null
},
"freshness": {
"state": "live",
"age_ms": 123,
"poll_interval_ms": 123
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Tennis scores entitlement required.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Prediction markets
Event-linked prediction-market order books with probability ladders, liquidity, and live updates.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Snapshot /v1/events/{event_id}/prediction-markets/orderbook/snapshot
Returns Polymarket and Kalshi order books linked to one canonical odds-api sports event. Each contract contains executable probability bid and ask ladders, top-of-book probability and size, the most recent trade probability when available, gross and estimated fee-adjusted decimal odds, liquidity metadata, and source freshness. Use `providers`, `market_keys`, and `contract_ids` to narrow the response and `depth` to bound each ladder. Market availability is curated to the API's supported sports offering.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/prediction-markets/orderbook/snapshot?market_keys=moneyline"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
providers
string
Comma-separated prediction-market provider allow-list: `polymarket`, `kalshi`.
market_keys
string
Comma-separated market key allow-list for odds filters.
contract_ids
string
Comma-separated contract ID allow-list from a prediction-market snapshot.
depth
integer
Number of probability price levels per bid/ask side. Use smaller values for lower latency and payload size.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Prediction-market order book: Snapshot
{
"event_id": "3704597661",
"as_of_ts_ms": 1760000000000,
"ttl_seconds": 30,
"items": [
{
"id": "polymarket::nba-example::moneyline",
"event_id": "3704597661",
"provider": "polymarket",
"provider_market_id": "nba-example",
"market_key": "moneyline",
"market_name": "Home vs Away",
"bet_type": "moneyline",
"period": "full time",
"home_team": "Home",
"away_team": "Away",
"status": "open",
"currency": "USD",
"size_unit": "contracts",
"total_liquidity": 4200.0,
"fee_model": "polymarket_sports_taker",
"fee_estimated": true,
"observed_at": "2026-08-26T08:00:00Z",
"contracts": [
{
"contract_id": "home-contract",
"contract_name": "Home",
"outcome": "yes",
"side": "home",
"status": "open",
"probability_bids": [
{
"price": 0.51,
"size": 120.0
}
],
"probability_asks": [
{
"price": 0.52,
"size": 95.0
}
],
"best_bid_probability": 0.51,
"best_bid_size": 120.0,
"best_ask_probability": 0.52,
"best_ask_size": 95.0,
"gross_decimal_odds": 1.92307692,
"fee_adjusted_decimal_odds": 1.88,
"projection_eligible": true
}
]
}
],
"next_cursor": null,
"resume": "1760000000000-0"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/events/{event_id}/prediction-markets/orderbook/stream
Server-Sent Events feed for prediction-market order-book changes on one event. Read the snapshot first, then reconnect with its `resume` token as `since`. Handle `delta`, `heartbeat`, and `resync`; reload the snapshot after `resync`.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/prediction-markets/orderbook/stream?market_keys=moneyline&since=1760000000000-0&catchup=true"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
providers
string
Comma-separated prediction-market provider allow-list: `polymarket`, `kalshi`.
market_keys
string
Comma-separated market key allow-list for odds filters.
contract_ids
string
Comma-separated contract ID allow-list from a prediction-market snapshot.
depth
integer
Number of probability price levels per bid/ask side. Use smaller values for lower latency and payload size.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Decoded delta message
event: delta
data: {
"event_id": "3704597661",
"resume": "1760000000000-0",
"changes": []
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/events/{event_id}/prediction-markets/orderbook/ws
WebSocket feed for prediction-market order-book changes on one event. Messages mirror the prediction-market SSE stream payloads and use the same filters and resume semantics.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/events/3704597661/prediction-markets/orderbook/ws?market_keys=moneyline&since=1760000000000-0&catchup=true&api_key=$ODDS_API_KEY"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
providers
string
Comma-separated prediction-market provider allow-list: `polymarket`, `kalshi`.
market_keys
string
Comma-separated market key allow-list for odds filters.
contract_ids
string
Comma-separated contract ID allow-list from a prediction-market snapshot.
depth
integer
Number of probability price levels per bid/ask side. Use smaller values for lower latency and payload size.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_unavailable
boolean
When true, include unavailable or suspended rows where the endpoint supports them.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"resume": "1760000000000-0",
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "3704597661",
"resume": "1760000000000-0",
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Racing events
Racing event discovery and live racing event updates.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Search /v1/racing/events
Searches upcoming and live horse, greyhound, and harness racing events across Australia (`AU`), New Zealand (`NZ`), Great Britain (`GB`), and Ireland (`IE`). Use canonical race types `horse-racing`, `greyhound-racing`, and `harness-racing`; legacy shorthand is normalized for backward compatibility. Returned combinations depend on the live schedule. Racing polling should use narrow time windows, stable cursors, and shorter intervals near jump. Omit status to discover early races: status=fetching excludes events still marked open, even when early odds exist. Event lifecycle status is distinct from each bookmaker odds snapshot status. Runner counts prefer Betfair's complete scratch-aware field, fall back to another bookmaker or the schedule, and expose source, timestamp, and completeness metadata. Racing includes every available bookmaker on every plan: the API key's odds and betting-opportunity bookmaker selections do not filter racing events, odds, streams, or links.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events?status=fetching&limit=25"
Parameters
Query
race_type
string
Comma-separated canonical racing type filters: `horse-racing`, `greyhound-racing`, or `harness-racing`. Legacy aliases such as `horse`, `thoroughbred`, `greyhound`, `dog`, `dogs`, and `harness` are normalized for backward compatibility.
race_state
string
Comma-separated racing state filters.
race_country
string
Comma-separated racing country filters: `AU`, `NZ`, `GB`, or `IE`. Returned combinations depend on the live racing schedule.
status
string
Comma-separated event lifecycle statuses. Omit for early discovery: fetching alone excludes open races that may already have prices. This is not the bookmaker odds snapshot status.
start_from
integer
Unix seconds lower bound for event start time. Use bounded windows in production polling.
start_to
integer
Unix seconds upper bound for event start time. Keep windows narrow for hot sync jobs.
cursor
string
Pagination cursor from the previous `next_cursor`. Keep filters identical between pages.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Racing events: Search
{
"items": [
{
"event_id": "race-1001",
"race_type": "horse-racing",
"race_country": "AU",
"race_state": "QLD",
"status": "open",
"race_start_time": 1760000000,
"race_venue": "Doomben",
"active_runners": 7,
"total_runners": 8,
"scratched_runners": 1,
"runner_count_source": "betfair",
"runner_count_updated_at_ts": 1759999700,
"runner_count_complete": true
}
],
"next_cursor": null,
"count": 1
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/racing/events/stream
Server-Sent Events feed for racing event inserts, updates, and removals. Store resume tokens and reload the event list if a stream asks the client to resync.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events/stream"
Parameters
Query
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Decoded delta message
event: delta
data: {
"resume": "1760000000000-0",
"changes": []
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/racing/events/ws
WebSocket feed for racing event inserts, updates, and removals. Messages mirror the racing events SSE feed.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/racing/events/ws?api_key=$ODDS_API_KEY"
Parameters
Query
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"resume": "1760000000000-0",
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"resume": "1760000000000-0",
"changes": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Event details /v1/racing/events/{event_id}
Returns the current racing event record for a canonical race ID.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events/RACE_EVENT_ID"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"event_id": "3704597661",
"data": {}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Racing odds
Racing odds snapshots, home racing feeds, Server-Sent Events, and WebSocket updates.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Snapshot /v1/racing/events/{event_id}/odds
Returns bookmaker odds snapshots for one racing event. Cache the last good snapshot with its timestamp and prefer streams for near-jump realtime displays. Compact WIN prices are at items[].runners[].win_odds. Exchange WIN-market volume is at items[].total_matched and matched runner volume, when supplied, is at items[].runners[].traded_volume. These are cumulative traded amounts, not current executable depth. Sportsbet raw prices, when requested, are at items[].payload.horse_data[].odds. Early odds status ok and near-jump status fetching can both contain valid prices. Top-level active_runners, total_runners, scratched_runners, runner_count_source, runner_count_updated_at_ts, and runner_count_complete describe the best available field state. Every available racing bookmaker is returned on every plan; the API key's odds and betting-opportunity bookmaker selections do not filter racing odds. Use the bookmakers parameter to narrow the response. Request include_source=true for snapshot timestamps and include_links=true for bookmaker_link, independently of include_raw_payload.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events/RACE_EVENT_ID/odds"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
include_links
boolean
Include bookmaker_link when available, independently of raw payload. Compact clients omit links by default. false removes links including nested raw links.
include_raw_payload
boolean
Include bookmaker-specific payload. Compact clients default to false and receive runners[].win_odds; Sportsbet raw WIN prices are payload.horse_data[].odds.
include_source
boolean
Include source metadata such as updated_at_ts (Unix seconds). Compact clients omit it by default.
include_unavailable
boolean
Include bookmaker snapshots without compact WIN or PLACE runner prices. This does not restrict odds to status fetching; early status ok may contain valid prices.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Racing odds: Snapshot
{
"event_id": "race-1001",
"as_of_ts_ms": 1760000000000,
"active_runners": 7,
"total_runners": 8,
"scratched_runners": 1,
"runner_count_source": "betfair",
"runner_count_updated_at_ts": 1759999700,
"runner_count_complete": true,
"items": [
{
"bookmaker_name": "betfair",
"race_id": "race-1001",
"status": "ok",
"total_matched": 24567.12,
"runners": [
{
"runner_number": "1",
"runner_name": "Example Runner",
"win_odds": 3.4,
"place_odds": 1.65,
"traded_volume": 4100.0
}
]
}
],
"resume": "1760000000000-0"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/racing/events/{event_id}/odds/stream
Server-Sent Events feed for racing odds changes on one event. Reconnect with `since=<last_resume>` and reload the snapshot after `resync`. Each changes[].snapshot uses the same compact runner fields, link flags and odds status meanings as the racing odds snapshot endpoint for compact clients. Non-compact clients with include_raw_payload=true receive raw bookmaker data directly in snapshot (Sportsbet: snapshot.horse_data[].odds), without a payload wrapper.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events/RACE_EVENT_ID/odds/stream?since=RACE_RESUME_TOKEN&catchup=true"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
include_links
boolean
Include bookmaker_link when available, independently of raw payload. Compact clients omit links by default. false removes links including nested raw links.
include_raw_payload
boolean
Include bookmaker-specific payload. Compact clients default to false and receive runners[].win_odds; Sportsbet raw WIN prices are payload.horse_data[].odds.
include_source
boolean
Include source metadata such as updated_at_ts (Unix seconds). Compact clients omit it by default.
include_unavailable
boolean
Include bookmaker snapshots without compact WIN or PLACE runner prices. This does not restrict odds to status fetching; early status ok may contain valid prices.
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Decoded delta message
event: delta
data: {
"event_id": "race-1001",
"resume": "1760000000000-0",
"changes": [
{
"op": "upsert",
"bookmaker_name": "sportsbet",
"snapshot": {
"bookmaker_name": "betfair",
"race_id": "race-1001",
"status": "ok",
"total_matched": 24567.12,
"runners": [
{
"runner_number": "1",
"runner_name": "Example Runner",
"win_odds": 3.4,
"place_odds": 1.65,
"traded_volume": 4100.0
}
]
}
}
]
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/racing/events/{event_id}/odds/ws
WebSocket feed for racing odds changes on one event. Messages mirror the racing odds SSE feed.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/racing/events/RACE_EVENT_ID/odds/ws?since=RACE_RESUME_TOKEN&catchup=true&api_key=$ODDS_API_KEY"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
include_links
boolean
Include bookmaker_link when available, independently of raw payload. Compact clients omit links by default. false removes links including nested raw links.
include_raw_payload
boolean
Include bookmaker-specific payload. Compact clients default to false and receive runners[].win_odds; Sportsbet raw WIN prices are payload.horse_data[].odds.
include_source
boolean
Include source metadata such as updated_at_ts (Unix seconds). Compact clients omit it by default.
include_unavailable
boolean
Include bookmaker snapshots without compact WIN or PLACE runner prices. This does not restrict odds to status fetching; early status ok may contain valid prices.
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
max_batch
integer
Maximum stream messages to read per batch. Default is 500; use smaller batches for low-latency clients.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "race-1001",
"resume": "1760000000000-0",
"changes": [
{
"op": "upsert",
"bookmaker_name": "sportsbet",
"snapshot": {
"bookmaker_name": "betfair",
"race_id": "race-1001",
"status": "ok",
"total_matched": 24567.12,
"runners": [
{
"runner_number": "1",
"runner_name": "Example Runner",
"win_odds": 3.4,
"place_odds": 1.65,
"traded_volume": 4100.0
}
]
}
}
]
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"event_id": "race-1001",
"resume": "1760000000000-0",
"changes": [
{
"op": "upsert",
"bookmaker_name": "sportsbet",
"snapshot": {
"bookmaker_name": "betfair",
"race_id": "race-1001",
"status": "ok",
"total_matched": 24567.12,
"runners": [
{
"runner_number": "1",
"runner_name": "Example Runner",
"win_odds": 3.4,
"place_odds": 1.65,
"traded_volume": 4100.0
}
]
}
}
]
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Racing history (beta)
Recorded racing price changes per race, bookmaker and runner from 8 November 2026. Beta; requires approval.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Past races (beta) /v1/racing/history/events
Beta. Lists races that racing price history holds, by the UTC day of their scheduled start, including races that have left `/v1/racing/events`. Filter with `country`, `race_type`, `venue` or `bookmaker`. History starts on 8 November 2026 19:38 UTC; nothing earlier exists. Requires racing access and the racing-history add-on (403 `racing_history_access_required` without it) and stays within the plan's history lookback.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/history/events?date=string"
Parameters
Query
date required
string (date)
UTC day of the scheduled start (YYYY-MM-DD).
country
string
race_type
string
Comma-separated canonical racing type filters: `horse-racing`, `greyhound-racing`, or `harness-racing`. Legacy aliases such as `horse`, `thoroughbred`, `greyhound`, `dog`, `dogs`, and `harness` are normalized for backward compatibility.
venue
string
bookmaker
string
Canonical bookmaker filter. Use `/bookmakers` or `/coverage` to discover supported keys.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
cursor
string
Pagination cursor from the previous `next_cursor`. Keep filters identical between pages.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Racing history: Past races (beta)
{
"date": "2026-11-12",
"items": [
{
"event_id": "ascot_3_horse-racing_1794492000",
"venue": "ascot",
"race_number": "3",
"race_type": "horse-racing",
"country": "GB",
"race_start_time": 1794492000,
"bookmakers": [
"betfair",
"paddypower",
"skybet",
"williamhill"
],
"first_tick_ts": "2026-11-11T14:02:11Z",
"last_tick_ts": "2026-11-12T14:41:07Z"
}
],
"count": 1,
"history_start": "2026-11-08T19:38:18Z"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Price history (beta) /v1/racing/events/{event_id}/odds/history
Beta. Returns the recorded price changes of one race as one series per bookmaker and runner, oldest first. Each point is the runner's full price state at the moment a price changed (`changed` names the fields that moved); unchanged re-reads are counted per bookmaker in `bookmakers[]`. Narrow with `bookmakers`, `market` (win, place) and `runner_number`, bound with `from_ts`/`to_ts` (the default window is 3 days before to 1 hour after the scheduled start) and page with `limit` and `meta.next_cursor`. `include_final=true` adds the last prices frozen at the jump. For betfair, `win_odds` is the best lay price as on live racing odds; `exchange` carries best back/lay with sizes and `bsp` the Betfair starting price (projected before the off, actual once reconciled) from the time those fields are recorded. History is written when each UTC hour closes (`meta.complete_through_ts`). It is a record of the feed, not a settlement source.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events/RACE_EVENT_ID/odds/history"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Query
bookmakers
string
Comma-separated bookmaker allow-list. Use `/bookmakers` to discover supported keys.
market
string
win, place or all.
runner_number
string
Only this runner's cloth number.
from_ts
string
ISO8601 UTC start timestamp for a bounded history query.
to_ts
string
ISO8601 UTC end timestamp for a bounded history query.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
cursor
string
Pagination cursor from the previous `next_cursor`. Keep filters identical between pages.
include_final
boolean
Include the last prices frozen at the jump.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Racing history: Price history (beta)
{
"event_id": "ascot_3_horse-racing_1794492000",
"market": "all",
"race": {
"venue": "ascot",
"race_number": "3",
"race_type": "horse-racing",
"country": "GB",
"race_start_time": 1794492000
},
"series": [
{
"bookmaker_name": "betfair",
"runner_number": "4",
"runner_name": "Example Runner",
"selection_id": "104992755",
"points": [
{
"tick_ts": "2026-11-12T14:35:02Z",
"is_available": true,
"win_odds": 5.1,
"exchange": {
"win": {
"back": 5.0,
"back_size": 120.5,
"lay": 5.1,
"lay_size": 80.1
},
"place": {
"back": 1.8,
"back_size": 60.0,
"lay": 1.85,
"lay_size": 41.2
}
},
"bsp": {
"win": {
"near": 5.2,
"far": 4.7
}
},
"liquidity": 80.1,
"traded_volume": 1520.4,
"changed": [
"exchange.win.back",
"win"
]
},
{
"tick_ts": "2026-11-12T14:40:21Z",
"is_available": true,
"win_odds": 4.9,
"bsp": {
"win": {
"actual": 4.92
},
"place": {
"actual": 1.81
}
},
"changed": [
"bsp.place.actual",
"bsp.win.actual"
]
}
]
}
],
"bookmakers": [
{
"bookmaker_name": "betfair",
"first_seen_ts": "2026-11-11T14:02:11Z",
"last_verified_ts": "2026-11-12T14:41:07Z",
"ticks": 412,
"verifications": 730
}
],
"meta": {
"from_ts": "2026-11-09T14:40:00Z",
"to_ts": "2026-11-12T15:40:00Z",
"source": "blob",
"points": 2,
"truncated": false,
"history_start": "2026-11-08T19:38:18Z",
"complete_through_ts": "2026-11-12T16:00:00Z"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Betting opportunities
Positive EV and arbitrage opportunity feeds.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Snapshot /v1/bets/snapshot
Returns current betting opportunities by strategy. Use `strategies`, `limit`, and `event_id` to keep the payload scoped to what your product needs. Poll at a bounded interval, cache the last good response, and show execution-risk language before any user-facing bet action.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/bets/snapshot?strategies=pos_ev&limit=25"
Parameters
Query
strategies
string
Comma-separated betting strategies or `all`.
limit
integer
Maximum items to return. Respect the caps returned by `/limits`.
event_id
string
Canonical event or race identifier from an event list response.
source
string
Live bet source: active, legacy, or admin-only hybrid
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Betting opportunities: Snapshot
{
"items": [
{
"id": "example-positive-ev",
"strategy": "pos_ev",
"event_id": "3704597661",
"bookmaker_name": "Bet365",
"selection_key": "moneyline:home",
"odds": 2.1,
"ev": 7.7
}
],
"resume": "{\"pos_ev\":\"1760000000000-0\"}"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (SSE) /v1/bets/stream
Server-Sent Events feed for betting opportunity inserts, updates, and removals. Use this for alerting instead of high-frequency snapshot polling. Source-binding response headers identify the requested logical live-bet source and per-strategy effective sources.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -N -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/bets/stream?strategies=pos_ev&since=1760000000000-0&catchup=true"
Parameters
Query
strategies
string
Comma-separated betting strategies or `all`.
event_id
string
Canonical event or race identifier from an event list response.
source
string
Live bet source: active, legacy, or admin-only hybrid
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
Responses
200 Server-Sent Events stream. Each message has an event name and JSON data payload.
text/event-stream · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Decoded delta message
event: delta
data: {
"resume": "1760000000000-0",
"events": []
}
Decoded heartbeat message
event: heartbeat
data: {}
Decoded resync message
event: resync
data: {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET Stream (WebSocket) /v1/bets/ws
WebSocket feed for betting opportunity inserts, updates, and removals. The accept handshake includes source-binding headers matching the SSE stream.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
wscat -c "wss://api.odds-api.net/v1/bets/ws?strategies=pos_ev&since=1760000000000-0&catchup=true&api_key=$ODDS_API_KEY"
Parameters
Query
strategies
string
Comma-separated betting strategies or `all`.
event_id
string
Canonical event or race identifier from an event list response.
source
string
Live bet source: active, legacy, or admin-only hybrid
price_fields
string
`odds`, `odds,novig`, `odds,fair`, or `all`. Compact clients default to `odds`; existing clients default to current full pricing fields.
include_links
boolean
When true, include bookmaker/deep-link fields such as match links and racing links.
include_raw_payload
boolean
When true, include raw stored payload/data objects where the endpoint exposes them.
include_source
boolean
When true, include per-line/per-bookmaker provenance and capture metadata. Top-level freshness fields are always kept.
include_debug_ids
boolean
When true, include internal/subgroup/opposing IDs useful for reconciliation.
since
string
Resume token from a previous snapshot or stream message. Pass it after reconnecting.
catchup
boolean
When true, return available missed stream events after `since` before waiting for new events.
heartbeat_sec
integer
Maximum seconds between messages: a `heartbeat` is sent whenever this long passes without another message. Valid range is 5-120.
Responses
101 WebSocket connection established. Messages are JSON objects.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"resume": "1760000000000-0",
"events": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
200 OpenAPI tooling compatibility response schema. Runtime WebSocket connections upgrade with 101.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Delta message
{
"event": "delta",
"data": {
"resume": "1760000000000-0",
"events": []
}
}
Heartbeat message
{
"event": "heartbeat",
"data": {}
}
Resync message
{
"event": "resync",
"data": {
"event_id": "3704597661",
"resume": null,
"reason": "trimmed"
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
Endpoint group
Results
Sports event result lookup.
Base URL https://api.odds-api.net/v1 Version 1.0.0 Source Live OpenAPI
GET Event result /v1/events/{event_id}/results
Returns the latest known result for a sports event, or `pending` until settled. Poll every 1-5 minutes after start, then back off once the event is final.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/events/3704597661/results"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Results: Event result
{
"event_id": "3704597661",
"status": "final",
"result": {
"home_score": 24,
"away_score": 18
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
GET GET racing events event_id results /v1/racing/events/{event_id}/results
Public Odds API operation. Authenticate with `X-API-Key`. Check timestamps before displaying prices and handle empty, stale, or suspended markets.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/events/RACE_EVENT_ID/results"
Parameters
Path
event_id required
string
Canonical event or race identifier from an event list response.
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"event_id": "3704597661",
"status": "available",
"result": {
"event_id": "3704597661",
"source": "sportsbet",
"observed_at_ts": 123,
"status": "provisional",
"placings": [
{
"runner_number": "string",
"runner_name": "string",
"position": 123,
"dead_heat": true
}
],
"scratchings": [
{
"runner_number": "string",
"runner_name": "string",
"withdrawn_at_ts": 123,
"exchange_reduction_factor": "string"
}
],
"dividends": [
{
"bet_type": "WIN",
"runner_number": "string",
"product": "string",
"pool": "string",
"amount": "string",
"unit_stake": "string",
"currency": "AUD"
}
],
"dividends_status": "pending",
"non_finishers": [
{
"runner_number": "string",
"runner_name": "string",
"code": "string"
}
],
"dead_heat": true
}
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
POST POST racing results /v1/racing/results
Public Odds API operation. Authenticate with `X-API-Key`. Check timestamps before displaying prices and handle empty, stale, or suspended markets.
Auth: X-API-Key Handle HTTP 429 with backoff and avoid tight polling loops.
Request example
curl -H "X-API-Key: $ODDS_API_KEY" "https://api.odds-api.net/v1/racing/results"
Request body
application/json · required
Generated sample
{
"event_ids": [
"3704597661"
]
}
Responses
200 Successful Response
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"items": [
{
"event_id": "3704597661",
"status": "available",
"result": {
"event_id": "3704597661",
"source": "sportsbet",
"observed_at_ts": 123,
"status": "provisional",
"placings": [
"string"
],
"scratchings": [
"string"
],
"dividends": [
"string"
],
"dividends_status": "pending",
"non_finishers": [
"string"
],
"dead_heat": true
}
}
]
}
400 Invalid request parameters or body.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
401 Missing or invalid credentials.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
403 Credentials are valid but do not allow this resource.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
404 Resource was not found.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
429 Rate limit exceeded.
application/json · value
Retry-After
integer
Seconds to wait before retrying when supplied by the limiter.
X-RateLimit-Limit
integer
Request bucket capacity for the active limiter bucket when supplied.
X-RateLimit-Remaining
integer
Approximate remaining requests in the active limiter bucket when supplied.
X-RateLimit-Bucket
string
Limiter bucket name that produced the response when supplied.
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}
500 Unexpected server error.
application/json · object
X-Request-ID
string
Request identifier: the client's `X-Request-ID` when it is 1-128 characters of letters, digits, `.`, `_`, `:` or `-`, otherwise a generated UUID. Quote it when contacting support.
Generated sample
{
"detail": "string",
"code": "string",
"request_id": "string"
}