API keys, scopes and rate limits
Before you integrate, it helps to know how access works: what a key looks like, what a scope limits, and how rate limits and caching behave. The OddsRelay access contract, in plain terms.
3 min read · Updated 27 Oct 2026
Access to an odds feed is more than a URL and a token. How keys are shaped, what a scope limits, and how rate limits and caching behave decide how cleanly the feed fits your code.
This guide covers the OddsRelay access contract at the level you need to plan an integration. Every parameter is in the API docs.
What a key looks like
OddsRelay keys are prefixed so you always know what you are holding: or_ for a server key, or_ for a browser key that only answers calls from its own websites. You send the key as a Bearer token in the Authorization header or as x-api-key, never in a query string, never in a URL.
Keys are stored hashed, so the raw secret is shown exactly once, when it is made. If a key leaks, you roll it: the new key works at once and the old one keeps working for 24 hours, so revoke it straight away. Treat a key like any other production secret.
What a key can reach
Every self-serve plan gets every bookmaker in every region and every product each region serves. A key can be narrowed below that, so a service that reads only one feed holds a key that reads only that feed.
A call outside the key's scope is refused with a 403 that names the axis, and a refusal costs nothing.
- Products: the six matched feeds, raw and historical odds.
- Region: the region the call names in
region=, one per call.
Tokens and the rate limit
Each account has one pool of tokens: a paid plan's resets every month, and the free plan gives 50,000 tokens for 14 days. A call's price comes from the feed and the filters you send, never from the size of the reply (a historical odds day file is priced per MB), and quote= prices any request for free before you make it.
Each account also has a rate limit, a cap on requests per 10 seconds and per minute, the same on every plan. The way to stay under both is to make each request cheaper. Historical odds day files download one at a time per account, and one more at once is refused with a 429 too_ and a Retry-After.
Cheap polling with ETag and 304
Data replies carry an ETag (a free quote never does). Send it back as If-None-Match on your next request and, if nothing has changed, you get a 304 Not Modified with no body, which costs no tokens and still counts towards the rate limit.
With gzip, this means you can poll at your own pace without re-downloading a reply you already hold.
Step by step
Get a key. Sign up free, then create an or_live_ server key in your dashboard. Store it as a secret. It is shown once.
Scope it. Narrow the key to the feed types that service reads.
Send the key in a header. Authorization: Bearer <key>, Accept-Encoding: gzip. Never put the key in the URL.
Cache your polls. Store the ETag and send If-None-Match next time, so an unchanged reply comes back as a cheap 304.
Where OddsRelay fits
Sign up free, and the key you create runs against this exact contract. Price any call first with a free quote=, so there are no surprises at cut-over.