Getting Started

1. Create a free account to get your API key
2. Find your key in the dashboard
3. Start making requests

Authentication

Include your API key as a query parameter on every request. Your key starts with oa_ and can be found in your dashboard. Keep it secret — if compromised, regenerate it instantly.

Never expose your API key in client-side code (browser JavaScript, mobile apps, etc). Always make API calls from your backend server to keep your key secure.

Coverage

We cover 10+ leagues, 100+ bookmakers (including clones), and a wide range of market types including head-to-head, spreads, totals, and player props. Available markets vary by sport and bookmaker.

See our full coverage page for a complete list of all available leagues, bookmakers, and market types per sport.

Credits

Each request costs credits based on the number of market types and bookmakers requested:

Every 5 bookmakers counts as 1 group (rounded up).

Examples

Credits are only deducted when data is returned. If your query returns no games, you are not charged.

Client Libraries

Official clients for Python and Node.js, plus an MCP server for AI assistants. They wrap the same API documented below, so anything you can do with a raw request you can do through them.

The client libraries are updated periodically, so new sports, markets and fields may reach the raw API first.

They save you writing the same plumbing every time: your key on every request, retries when one fails, reconnecting and re-subscribing when the WebSocket drops, game matching across bookmakers and they even include an arbitrage and value bet finder.

You do not need them. The API is plain HTTP and JSON, so if you would rather not add a dependency, or you work in another language, go straight to the endpoint reference. The cURL, Python and JavaScript examples further down use nothing but a HTTP client.

Python SDK

PyPIGitHub

The official Python client. Handles auth and retries for you, and returns typed responses. Requires Python 3.9 or newer.

Quickstart

It also wraps the WebSocket stream (reconnecting and re-subscribing on its own), the results API, and has arbitrage and value bet finders built in. See the README for the full reference.

Node.js SDK

npmGitHub

The official Node client. Written in TypeScript and ships its own type definitions, so it works the same from plain JavaScript. Requires Node 18 or newer.

Quickstart

CommonJS works too with const { RapidOddsAPI } = require("rapidoddsapi"). The WebSocket stream, results API, and the arbitrage and value bet finders are all included. See the README for the full reference.

MCP Server

PyPIGitHub

Connects RapidOddsAPI to an AI assistant over the Model Context Protocol, so it can pull live odds, scores and value bets on its own. Built on the Python SDK.

Claude Desktop

Add this to your claude_desktop_config.json, then restart Claude Desktop:

Tools

Every response ends with what the call cost and how many credits are left, so the assistant can see its own spend.

Endpoint

One endpoint for everything. Choose your sport, pick the bookmakers and market types you want.

Parameters

Example

Response

Exchange lines are only returned when both sides are priced and their combined implied probability is 130% or less, to filter out lines nobody is actively trading. Thin lines can still appear, so check liquidity.

Rate Limiting

All plans are limited to 30 requests per second per API key. Exceeding this limit returns a 429 error.

Error Codes

Code Examples

Overview

The WebSocket feed pushes fresh odds data directly to you the moment each scraping cycle completes — no polling required. You connect once, subscribe to the sports and bookmakers you want, and receive updates automatically.

WebSocket access is included on the Pro and Elite plans. See pricing for details.

The data pushed over WebSocket is identical in structure to the REST endpoint response — the same sports, bookmakers, market types, and credit formula apply.

Connecting

Connect using your API key as a query parameter:

Once connected, the server sends a confirmation message:

Messages

Sending — Subscribe

After connecting, send a subscribe message to start receiving pushes for a sport. You can subscribe to multiple sports by sending one message per sport.

Sending — Unsubscribe

Receiving — Unsubscribed

Receiving — Subscribed

Sent immediately after a successful subscribe. Includes the credit cost per push for your subscription.

Receiving — Odds Update

Sent each time a scraping cycle completes for your subscribed sport. The data field is identical in structure to the REST endpoint response.

Receiving — Error

Credits

Credits are charged per push, not per connection. The same formula as the REST endpoint applies:

The credit cost for your subscription is shown in the credits_per_push field of the subscribed confirmation. Credits are only deducted when a push contains data — if a scrape cycle returns no games, you are not charged.

If you have insufficient credits when a push is triggered, you will receive an error event and the push will be skipped.

Error Codes

WebSocket errors fall into two categories — connection rejections (before the connection is established) and in-session error events (sent as messages after connecting).

Code Examples

Overview

Pre-race fixed odds for every Australian and New Zealand thoroughbred and harness race and every Australian greyhound race: win and place prices for every runner, from every bookmaker we cover. Pick the code with the code parameter (default thoroughbred).

After each race, /results gives every runner's finishing position and margin, under the same race_id, kept for 30 days.

Included in Pro, Elite and the Racing plan. Same API key as everything else. Racing uses no credits.

Runners are numbered the same at every bookmaker, so compare prices by number. Track names are spelled the same at every bookmaker too.

Meetings

What's on: every track and its upcoming races. No odds.

Races

Odds for one race, or for every race at one meeting. Pass either race_id or track.

last_update is when that bookmaker's prices for the race were last refreshed. The bookmaker's start_time is the start time that bookmaker shows; it can lag behind for a minute or two when a race is delayed. url is the race's page on that bookmaker's website (null when we have no link for it).

status is open, closed (that bookmaker closed betting at the jump; its prices are the last ones offered) or abandoned for that bookmaker. The race's closed and abandoned are true once two or more bookmakers say so, or the only bookmaker on the race does. They count every bookmaker, even when you filter with bookmakers. An abandoned race is never closed.

Results

Finishing positions and margins for every runner. Every parameter is optional: with none you get every result so far today. Results are kept for 30 days, under the same race_id as the odds.

status is interim (usually the winner only, a couple of minutes after the race), final, or abandoned (no runners). A final result often lists the first four placings first and the rest of the field a few minutes later.

Runners are in finishing order, with scratched runners last. margin is lengths behind the winner. A dead heat shows as two runners with the same position. Join to the odds on race_id and runner number.

Flucs

Price fluctuations for one race: each bookmaker's first recorded price for every runner, then every change. Kept for 3 days, for showing flucs on today's races. Not a historical archive.

flucs starts with the first price we recorded, up to 24 hours before the race, and adds a point only when the price changes. Races priced earlier than that may already have moved before the first point. Prices are checked hourly when a race is more than 12 hours away, then more often as it gets closer: every 15 minutes, 5 minutes, 2 minutes, 1 minute, and every 10 seconds in the last 5 minutes until the jump. The last point is the latest recorded price. For live prices use /races or the WebSocket. Scratched runners get no new points.

WebSocket

Live push. Every time a bookmaker changes a race, you get that bookmaker's full runner list for that race.

Subscribe

Subscribe by track. A track subscription covers every upcoming race there, today and on future days, so you only subscribe once per connection. "*" means every track.

Each subscribe adds to what you already have. To stop, send {"action": "unsubscribe", "tracks": ["Orange"]} or {"action": "unsubscribe", "all": true}. After a reconnect, send your subscribe again.

Messages you receive

In a race_update, start_time is the race's start time (the one most bookmakers agree on) and book_start_time is that bookmaker's own. New races arrive as race_update messages as soon as a bookmaker lists them. There is no separate "new race" event.

Each bookmaker that abandons the race also sends a race_update with status: "abandoned" and no prices.

Each bookmaker that closes the race also sends one race_update with status: "closed" and its last prices. Races keep updating for up to 15 minutes after their start time, then stop. When a race is delayed, the 15 minutes count from the new time as soon as two bookmakers show it.

A race can send several race_result messages: interim, then final, then final again when the rest of the field is added. Each one holds the full runner list, so just keep the latest.

Limits & Errors

REST errors

Errors come back as {"detail": "..."}.

WebSocket close codes

Code Examples

Overview

The Results API returns live scores, period breakdowns, and full player stat lines for every game we cover. Use it to track games in play, or to settle bets once a game finishes.

It runs on its own endpoint but uses the same API key as the odds API, so there is nothing extra to set up.

See our full coverage page for the sports and player stats available. Requesting a sport we do not cover returns a 404 listing the sports that are.

Endpoint

One endpoint. Filter by status to get only the games you care about, and use include to control how much data comes back.

Parameters

We keep concluded games for 7 days so there is a window to settle against, then they are removed. Use days to trim that down when you only care about recent games, for example days=1 on a busy slate to get today's games without a week of history behind it. It is an upper bound rather than a guarantee, so asking for more days than we hold is not an error, you just get everything there is.

Game status values

These three values are the same across every sport, whatever the underlying competition calls them. The upcoming filter maps to SCHEDULED. Games that have not started carry only the game block, with no score or players.

Example

The same response for another sport

Same structure, same field names. Only the scoring fields, the stat fields and the name of the mid-game total change. Here a LIVE MLB game, where a period is an inning.

Note full_time is null because the game is still live, while first_5_innings is populated because those innings have finished. Innings are trimmed here for length.

Response

Periods

The response shape is identical for every sport. A period is whatever that sport divides a game into, whether a quarter, a half or an inning, and by_period always holds the raw per-period values you can build any period market from. Only the stat field names change between sports. Because a period means different things, treat the period numbers as opaque: period 2 is half time in one sport and quarter time in another.

The live clock

Inside period_state[], each sport carries the clock its own competition keeps. They are not interchangeable, so the field name states both things you need to know: which window it measures and which way it counts, as {scope}_seconds_{direction}.

A sport carries whichever of these its competition actually publishes, so read the field that is present rather than assuming one. Baseball has no clock at all and carries half instead. Only the period in progress carries a clock, with one exception: AFL keeps period_seconds_elapsed on finished quarters too, because its feed records how long each one ran.

The clock is for display. Nothing settles from it, and it is not a countdown to the end of a period unless the field says remaining. AFL is the clearest case: its clock includes time-on, so a nominal 20 minute quarter runs anywhere from about 1760 to 2020 seconds and there is no fixed length to count down from. Use completed to know a period is over.

Player fields

A player who fills two roles appears once with both sets of fields. An MLB two-way player carries the batter_ and pitcher_ fields together, and fields for a role a player did not fill are simply absent rather than zero.

Markets about who scored first read the player field, not scoring_events. A market like player_1st_tryscorer is already resolved to a boolean on that player, so you never have to walk the list yourself. scoring_events is there to show the sequence live, and to check a settlement against if one is ever queried.

Timestamps

Timestamps are UTC and use the same format as the odds API. Start times for the same game can differ slightly between the two, so match games on team names plus a time window rather than an exact timestamp. Our guide on matching games across bookmakers shows the approach.

Settling Bets

If you are tracking bets taken from the odds API and want to settle them automatically, this section covers what you need. The two APIs share standardised team and player names, so a bet recorded against a market key and a selection can be resolved straight from the results data once the game is done.

Market to field map

A few examples of how odds API markets line up with the results data. The rest follow the same patterns.

Dots below show where a value sits in the nested response, so score.totals.half_time.points means the points value inside half_time, inside totals, inside score.

The pattern holds across the rest. Team markets read from score.home or score.away, a market covering part of a game reads that sport's named total (half_time, or first_5_innings for MLB) or the matching entries in the period arrays, single period markets read the matching entry in score.totals.by_period, and every player market maps to the stat field of the same name.

Player stat fields are named after the market key, so batter_hits settles from players[].batter_hits with no lookup table. A _milestones market settles from the same field as its base market.

Player and team names are standardised across both APIs, so they join directly. See the coverage page for the full market list.

Handicaps in detail

Handicaps are the one case where the match margin alone is not enough. Each outcome carries its own signed point, so a bet is settled from the point of view of the team that was backed, not the home team.

Using the example game above, Adelaide Crows 74 and Collingwood 108:

First half handicaps settle the same way, using the first half's entries in the two _by_period arrays in place of the final scores. That is periods 1 and 2 in a sport played in quarters, but period 1 alone in a sport played in halves, so read period_state[] rather than assuming two.

Credits

Results requests cost a flat 1 credit each, no matter how many games come back or how much detail you include.

As with odds, credits are only deducted when data is returned. Polling status=live with no games in play costs nothing.

Results and odds requests draw from the same monthly credit allowance. See pricing.

Error Codes

An unknown game_id is not an error. It returns 200 with an empty games array, and costs no credits.

Code Examples

Connecting

The results WebSocket pushes fresh scores and player stats every time a scrape cycle completes. See coverage for update frequencies. It is a separate endpoint from the odds WebSocket, and is included on the Pro and Elite plans.

Once connected, the server sends a confirmation message:

Messages

Sending — Subscribe

The status, include and days fields work exactly as they do on the REST endpoint, and all are optional. Subscribing to live is the usual choice for score tracking.

Sending — Unsubscribe

Receiving — Subscribed

Receiving — Results Update

Sent each time a scrape cycle completes. The data field is identical in structure to the REST response, and the same rule applies: full_time is null until a game is CONCLUDED.

Receiving — Error

Code Examples

Futures API

Overview

Outright markets that run for a whole season, such as the winner of a competition or an award. They have no fixture, so they use their own endpoint rather than the odds one.

Same API key and the same credit cost as the odds API. REST only, no WebSocket.

Endpoint

Parameters

Credits are charged the same way as the odds endpoint: market_types × ceil(bookmakers / 5), and nothing is charged when no markets come back. Error codes are the same too, listed under Error Codes.

Some market keys name the player they exclude, for example brownlow_medal_winner_without_daicos. These are replaced each season rather than carried forward, since the excluded player changes.

Response

The same shape as the odds endpoint without the fixture: bookmakers → markets → outcomes. There is no games array, since a futures market has no game to sit under.

To compare prices, group a market's outcomes across bookmakers by outcome name. Names are standardised, so the same runner is spelled identically in every feed.

Outcome qualifiers

In most futures markets the outcome name is the player or club being bet on. Vote total and 3 Vote Games markets work differently: one key covers many players or clubs, so each outcome carries extra fields saying which one it belongs to. All are optional and appear only where they apply.

On these markets name is only "Over" or "Under", so group by the qualifier rather than by name.

brownlow_3_votes covers every game of every round under one key. Filter on round and game for the ones you want. Most games include an "Any other player" outcome for the rest of the field.

Code Examples