> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therundown.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Quickstart
> Get your first API response, understand your usage headers, and choose the right update path.
## 1. Get your API key
Sign up at [therundown.io/api](https://therundown.io/api) to get your API key.
## 2. Make your first request
```bash cURL theme={null}
curl -H "X-TheRundown-Key: YOUR_API_KEY" \
"https://therundown.io/api/v2/sports"
```
```python Python theme={null}
import requests
response = requests.get(
"https://therundown.io/api/v2/sports",
headers={"X-TheRundown-Key": "YOUR_API_KEY"},
)
print(response.json())
```
```javascript JavaScript theme={null}
const response = await fetch(
"https://therundown.io/api/v2/sports",
{
headers: { "X-TheRundown-Key": "YOUR_API_KEY" },
}
);
const data = await response.json();
console.log(data);
```
```go Go theme={null}
package main
import (
"fmt"
"io"
"net/http"
)
func main() {
req, _ := http.NewRequest("GET", "https://therundown.io/api/v2/sports", nil)
req.Header.Set("X-TheRundown-Key", "YOUR_API_KEY")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))
}
```
```ruby Ruby theme={null}
require 'net/http'
require 'json'
uri = URI("https://therundown.io/api/v2/sports")
req = Net::HTTP::Get.new(uri)
req["X-TheRundown-Key"] = "YOUR_API_KEY"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(req)
end
puts JSON.parse(response.body)
```
Some reference endpoints are public, but authenticating from the start lets you see the same headers and behavior your production integration will use.
You'll receive a list of available sports with their IDs. A shortened example:
```json theme={null}
{
"sports": [
{ "sport_id": 1, "sport_name": "NCAA Football" },
{ "sport_id": 2, "sport_name": "NFL" },
{ "sport_id": 3, "sport_name": "MLB" },
{ "sport_id": 4, "sport_name": "NBA" },
{ "sport_id": 5, "sport_name": "NCAA Men's Basketball" },
{ "sport_id": 6, "sport_name": "NHL" },
{ "sport_id": 38, "sport_name": "TENNIS.ATP" },
{ "sport_id": 39, "sport_name": "TENNIS.WTA" }
]
}
```
## 3. Get today's NBA odds
The `offset` parameter shifts the date boundary so a "day" aligns with the timezone you care about instead of midnight UTC. Use the offset that matches your market timezone. See the [Events reference](/api-reference/generated/v2-events/get-events-with-markets-for-a-sport-and-date) for examples.
```bash cURL theme={null}
curl -H "X-TheRundown-Key: YOUR_API_KEY" \
"https://therundown.io/api/v2/sports/4/events/2026-02-12?market_ids=1,2,3&affiliate_ids=19,23&main_line=true&offset=300"
```
```python Python theme={null}
import requests
from datetime import date
response = requests.get(
f"https://therundown.io/api/v2/sports/4/events/{date.today()}",
headers={"X-TheRundown-Key": "YOUR_API_KEY"},
params={
"market_ids": "1,2,3", # Moneyline, Spread, Total
"affiliate_ids": "19,23",
"main_line": "true",
"offset": "300", # Example offset; adjust for your timezone
}
)
for event in response.json()["events"]:
teams = event["teams"]
print(f"{teams[0]['name']} @ {teams[1]['name']}")
for market in event.get("markets", []):
print(f" {market['name']}")
for participant in market["participants"]:
for line in participant["lines"]:
for aff_id, price in line["prices"].items():
print(f" {participant['name']}: {price['price']}")
```
```javascript JavaScript theme={null}
const today = new Date().toISOString().split("T")[0];
const response = await fetch(
`https://therundown.io/api/v2/sports/4/events/${today}?market_ids=1,2,3&affiliate_ids=19,23&main_line=true&offset=300`,
{
headers: { "X-TheRundown-Key": "YOUR_API_KEY" },
}
);
const data = await response.json();
for (const event of data.events) {
console.log(`${event.teams[0].name} @ ${event.teams[1].name}`);
for (const market of event.markets || []) {
console.log(` ${market.name}`);
}
}
```
In production, `market_ids`, `affiliate_ids`, and `main_line=true` are your biggest levers for controlling payload size and data-point usage.
## 4. Choose your update path
Every plan can use delta endpoints for efficient polling:
```bash theme={null}
curl -H "X-TheRundown-Key: YOUR_API_KEY" \
"https://therundown.io/api/v2/markets/delta?sport_id=4&market_ids=1,2,3&last_id=0"
```
If your key has `X-Websocket-Access: true`, you can also connect directly to the WebSocket feed for real-time updates:
```javascript theme={null}
const ws = new WebSocket(
"wss://therundown.io/api/v2/ws/markets?key=YOUR_API_KEY&sport_ids=4"
);
ws.onmessage = (event) => {
const msg = JSON.parse(event.data);
if (msg.meta?.type === "heartbeat") return;
const d = msg.data;
console.log(`Price update: event=${d.event_id} market=${d.market_id} price=${d.price}`);
};
```
WebSocket access is enabled on real-time tiers by default. If your key does not have it, use market delta polling instead.
## Next steps
Learn about all auth methods
Understand data points and `429` responses
Step-by-step guide
Delta, caching, and cost control
All market types and their IDs
Real-time data guide