Quick start

Odds API docs

Make one server-side request first. Then move through coverage, events, streaming updates, limits, caching, and endpoint groups as needed.

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"

Base URLhttps://api.odds-api.net/v1 AuthX-API-Key FormatJSON responses, SSE streams, WebSocket streams

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

Authenticate server-side

Send X-API-Key from your backend. Do not expose keys in browser-visible code.

Discover coverage

Build filters from coverage, sports, leagues, bookmakers, and bookmaker country routes.

Page events

Call event routes with a narrow time window, limit, and cursor until next_cursor is empty.

Load odds snapshots

Fetch an event odds snapshot for initial state and store as_of_ts_ms, ttl_seconds, next_cursor, and resume.

Stream hot updates

For realtime products, connect to SSE or WebSocket streams after the snapshot and resume with since on reconnect.

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.

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 or History Pro 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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. 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
  }
}

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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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.

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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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, and periods. 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 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.

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.

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) 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.

market_keys

string

Comma-separated market key allow-list for odds filters.

periods

string

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

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.

market_keys

string

Comma-separated market key allow-list for odds filters.

periods

string

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

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

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

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

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"
}

Endpoint group

Sports exchange

Sports betting exchange order books with back/lay ladders, liquidity, and live updates.

Base URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive OpenAPI

GET Snapshot /v1/events/{event_id}/exchange/orderbook/snapshot

Returns sports betting exchange order books for one event. Supported exchanges are betdaq, 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.

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 `betdaq`, `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

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 `betdaq`, `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

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}/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 `betdaq`, `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

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"
}

GET Discover markets /v1/events/{event_id}/exchange/markets

Lists available Betfair markets across sports, including soccer and cricket. Supply a WagerWise event ID 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; Betfair IDs are numeric event IDs, not market IDs.

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 WagerWise 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 WagerWise 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 WagerWise 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 WagerWise'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.

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"

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

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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive OpenAPI

GET Snapshot /v1/events/{event_id}/prediction-markets/orderbook/snapshot

Returns Polymarket and Kalshi order books linked to one canonical WagerWise 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 WagerWise'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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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

Betting opportunities

Positive EV, arbitrage, middle, and bonus-bet opportunity feeds.

Base URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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 URLhttps://api.odds-api.net/v1 Version1.0.0 SourceLive 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": "string",
    "observed_at_ts": 123,
    "status": "provisional",
    "placings": [
      {
        "runner_number": "string",
        "runner_name": "string",
        "position": 123
      }
    ],
    "scratchings": [
      {
        "runner_number": "string",
        "runner_name": "string"
      }
    ],
    "dividends": [
      {
        "bet_type": "WIN",
        "runner_number": "string",
        "product": "string",
        "pool": "string",
        "amount": "string",
        "unit_stake": "string",
        "currency": "AUD"
      }
    ],
    "dividends_status": "pending",
    "revision": 123,
    "updated_at_ts": 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"
}

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": "string",
        "observed_at_ts": 123,
        "status": "provisional",
        "placings": [
          "string"
        ],
        "scratchings": [
          "string"
        ],
        "dividends": [
          "string"
        ],
        "dividends_status": "pending",
        "revision": 123,
        "updated_at_ts": 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"
}