Everything you need to build on Orbistats
One reference for every endpoint, every parameter and every response shape across sports, odds and stats — organized by sport, then by resource. Pick a topic below or use the index to jump straight to it.
Three steps to your first request
Every integration starts the same way, regardless of which sport or product you're building on.
-H "Authorization: Bearer YOUR_API_KEY"
One base URL, one active version
All endpoints are served from a single host and versioned in the path. The current stable version is v1.
Breaking changes are only ever shipped behind a new version number (v2, etc.), never on v1 directly. Non-breaking additions — new fields, new optional parameters — can appear on the current version at any time, so integrations should ignore unrecognized fields rather than fail on them.
Authorization: Bearer YOUR_API_KEY
Every request — across every sport and every product — is authenticated the same simple way, using a single API key as a Bearer token.
-H "Authorization: Bearer YOUR_API_KEY"
A request made without a valid key returns 401 Unauthorized:
"error": {
"code": "invalid_api_key",
"message": "The API key provided is invalid or has expired.",
"status": 401
}
}
Plain JSON in, structured JSON out
Every successful response shares the same envelope: a data array, a meta object, and — where applicable — a pagination object.
"data": [
{
"fixture_id": "f_9231",
"home_team": "Arsenal",
"away_team": "Chelsea",
"kickoff": "2026-09-14T15:00:00Z",
"competition": "Premier League"
}
],
"meta": { "sport": "football", "count": 1 },
"pagination": { "page": 1, "per_page": 25, "total_pages": 4, "total_results": 87 }
}
All timestamps are ISO 8601 in UTC. All IDs are opaque strings — treat them as identifiers, not sequential numbers, since formats can vary by sport.
Sport → Resource → Endpoint
Every sport follows the same shape, so once you've learned one integration you've learned them all — swap the sport segment and the resource stays identical.
GET /v1/football/results
GET /v1/football/standings
GET /v1/football/odds
GET /v1/basketball/fixtures
GET /v1/cricket/fixtures
Currently supported sport segments: football, basketball, american-football, cricket, tennis, horse-racing, baseball, esports, golf, combat-sports. See the Sports coverage pages for what's available in each.
Core resources, available per sport
The same 14 resource types repeat across every sport. Replace {sport} with any supported segment. Full parameters and response fields live in the API Reference.
| Endpoint | Description |
|---|---|
GET/v1/{sport}/fixtures | Upcoming and past scheduled matches |
GET/v1/{sport}/fixtures/{id} | Full detail for a single fixture |
GET/v1/{sport}/results | Completed match results |
GET/v1/{sport}/standings | Current league or competition table |
GET/v1/{sport}/odds | Pre-match and live odds, normalized across books |
GET/v1/{sport}/statistics | Team and player statistics for the current season |
GET/v1/{sport}/lineups/{fixture_id} | Starting lineups and formations for a fixture |
GET/v1/{sport}/events/{fixture_id} | Play-by-play match events in sequential order |
GET/v1/{sport}/teams | Team directory and metadata |
GET/v1/{sport}/teams/{id} | Single team profile |
GET/v1/{sport}/players | Player directory and metadata |
GET/v1/{sport}/players/{id} | Single player profile and season stats |
GET/v1/{sport}/competitions | Leagues, tournaments and cups |
GET/v1/{sport}/countries | Supported countries and regions |
Common query parameters
Most list endpoints accept the same filtering and pagination parameters.
| Parameter | Type | Description |
|---|---|---|
date | string | Filter fixtures or results to a specific date (YYYY-MM-DD) |
season | string | Filter by season, e.g. 2025-2026 |
team_id | string | Filter results to a specific team |
competition_id | string | Filter to a specific league or tournament |
page | integer | Page number for paginated results (default 1) |
per_page | integer | Results per page, max 100 (default 25) |
Pagination state is always returned in the pagination object shown above — use total_pages to know when to stop requesting further pages.
Limits scale with your plan
Every response includes rate-limit headers so you always know where you stand.
| Plan | Requests / min | Requests / month | Overage |
|---|---|---|---|
| Free | 30 | 10,000 | Requests blocked until next window |
| Starter | 120 | 250,000 | Billed per additional 1,000 calls |
| Growth | 600 | 2,000,000 | Billed per additional 1,000 calls |
| Enterprise | Custom | Custom | Dedicated infrastructure & SLA |
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1757861400
See Pricing for full plan details, or talk to sales about a custom Enterprise limit.
Consistent error shape, every time
Every error response uses the same envelope, regardless of endpoint or sport.
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry after the window resets.",
"status": 429
}
}
| Status | Meaning | Common cause |
|---|---|---|
400 Bad Request | The request was malformed | Invalid parameter value or missing required field |
401 Unauthorized | Authentication failed | Missing, invalid or expired API key |
403 Forbidden | Authenticated but not permitted | Your plan doesn't include this endpoint or sport |
404 Not Found | Resource doesn't exist | Invalid fixture_id, team_id, etc. |
429 Too Many Requests | Rate limit exceeded | Too many requests in the current window |
500 Internal Server Error | Something failed on our end | Rare — check Status and retry with backoff |
Push updates instead of polling
For live scores and odds, don't poll — subscribe instead. Two options, depending on your architecture.
We POST a JSON payload to a URL you register the moment an event happens — a goal, a final whistle, an odds change.
"event": "fixture.finished",
"sport": "football",
"fixture_id": "f_9231",
"final_score": { "home": 2, "away": 1 },
"timestamp": "2026-09-14T16:52:03Z"
}
Open one persistent connection and receive every update as it happens — the lowest-latency option for live boards and trading.
Same call, your language
Official client libraries handle auth headers, retries and pagination for you.
-H "Authorization: Bearer YOUR_API_KEY"
headers: { Authorization: 'Bearer YOUR_API_KEY' }
});
const data = await res.json();
res = requests.get(
"https://api.orbistats.com/v1/football/fixtures",
params={"date": "2026-09-14"},
headers={"Authorization": "Bearer YOUR_API_KEY"}
)
data = res.json()
See the full SDKs page for install instructions, TypeScript types and more languages.
What changed, and when
Non-breaking changes ship continuously; breaking changes only ever land on a new version. Subscribe to the changelog to track both.
Common questions
Do I need a different API key for each sport?
No. A single API key authenticates every sport and product included in your plan — football, basketball, cricket and the rest all use the same key.
What format are timestamps returned in?
All timestamps are ISO 8601 in UTC, for example 2026-09-14T15:00:00Z. Convert to a local time zone on the client side.
Is there a free tier?
Yes. The Free plan includes live access to core endpoints at a lower rate limit, with no credit card required to start.
How do I get real-time updates instead of polling?
Use Webhooks for event-driven push updates, or the WebSocket API for a persistent low-latency streaming connection.
How far back does historical data go?
Coverage varies by sport and competition. Check the competitions endpoint for season availability, or contact sales for deep historical archives.
What happens if I exceed my rate limit?
You'll receive a 429 response with a Retry-After header. Requests resume automatically once the current window resets.
Related pages
Explore more of the developer platform.
Start free. Upgrade when you need enterprise SLAs.
Self-serve API keys for developers today — dedicated infrastructure, custom feeds and SLAs when you're ready.