---
title: "Get odds by sport"
method: GET
path: "/v1/sports/{sport_key}/odds"
tags: ["Sports"]
---

# Get odds by sport

`GET /v1/sports/{sport_key}/odds`

## Request

- Base URL: `https://api.puntersedge.online`
- URL: `https://api.puntersedge.online/v1/sports/{sport_key}/odds`
- Auth: API key in header `X-API-Key`

Cost: 1 credit per requested market. Parameters: sport_key selects the sport (for example afl or nrl); markets is a comma-separated list such as h2h,spreads,totals; bookmakers optionally filters bookmaker keys; oddsFormat accepts decimal or american.

`markets` is deduplicated and validated before billing, so a repeated market is charged
once and an unknown one is a free 422 rather than a paid empty list.

There is no racing sport_key. For horse, harness or greyhound racing use
GET /v1/racing/next-to-go (2 credits) or GET /v1/racing/events instead — passing
'horse-racing' here returns 404, because racing is a separate endpoint family.

**Pre-match only. There is no in-play feed.** An event is listed until its `commence_time`
and leaves this endpoint the moment it starts; no bookmaker connector reads in-play
markets, so nothing here updates during a match. The last pre-match prices for an event
that has started are kept in GET /v1/sports/{sport_key}/odds/history and the move feed
at GET /v1/sports/{sport_key}/odds/movements. (Documented 2026-09-10 after a customer
polled a game through kick-off expecting live prices.)

## Path parameters

- `sport_key` string, required

## Query parameters

- `markets` string: Comma-separated: h2h,spreads,totals
- `bookmakers` string: Comma-separated bookmaker keys, or omit for all. Case-insensitive. An unrecognised key is a free 422 naming the valid keys, so a typo costs nothing.
- `competition` string: Filter to one competition, case-insensitive exact match (e.g. NRLW). A value this sport has never carried is a 422 listing the ones it has, not an empty 200 — see `include_unknown_competition` for why that distinction matters. See the `competition` field on each event.
- `include_unknown_competition` boolean: When filtering by `competition`, ALSO return events whose competition is null — not every bookmaker supplies one, and on some sports most of the card is unlabelled (ncaaf 40 of 47 upcoming events, tennis_atp 21 of 72). Because of this the filter is 'this competition OR unlabelled', so a result set is not proof that the competition matched anything: an unrecognised value is rejected with 422 rather than answering with the unlabelled events alone. Set false for a strict exact match that returns only events explicitly labelled with this competition.
- `oddsFormat` string: decimal or american
- `maxAgeMinutes` integer: Exclude bookmaker markets older than this many minutes; default 360 allows 3-hour supplemental feeds while hiding multi-day stale prices.

## Headers

- `X-API-Key` string
- `X-RapidAPI-Proxy-Secret` string

## Response `200`

Successful Response

- SportOddsEventOut[]
  - `id` string, required
  - `sport_key` string, required
  - `sport_title` string, required
  - `commence_time` string, required
  - `home_team` string, nullable, required
  - `away_team` string, nullable, required
  - `competition` string, nullable
  - `bookmakers` object[], required
  - `odds_format` string, nullable
  - `fetched_at` string, nullable
  - `data_age_seconds` integer, nullable
  - `freshest_age_seconds` integer, nullable
  - `stale` boolean
  - `stale_bookmakers` string[]
  - `cached` boolean, nullable
  - `cache_age_seconds` integer, nullable
  - `canonical_event_id` string, nullable
  - `data_quality` object, nullable

## Other responses

- `401`: Missing or invalid API key. Send `X-API-Key`. See https://puntersedge.online/developers/errors
- `402`: Monthly credit allowance exhausted for this plan. Upgrade at https://puntersedge.online/api/pricing
- `422`: Validation Error
- `429`: Rate limit exceeded for this plan. Honour the `Retry-After` header (seconds) before retrying. See https://puntersedge.online/developers/rate-limits
- `500`: Unexpected server error. Safe to retry with backoff.

---

[API](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api.md) · [All operations](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/puntersedge/apis/puntersedge-odds-api/revisions/f35b6aab1946?raw)