Response Format & Status Codes

Every V1 endpoint returns the same envelope so you can write one parser for the whole API.

Envelope

{
  "success": true,
  "type": "live",
  "cacheHit": false,
  "sport": "football",
  "data": { ... }
}

Field	Type	Meaning
`success`	`boolean`	`true` for any 2xx response.
`type`	`string`	Endpoint identifier, e.g. `live`, `game`, `standings`, `brackets`, `search`.
`cacheHit`	`boolean`	`true` when served from the in-memory cache. Useful for monitoring.
`sport`	`string`	Sport slug (only on sport-scoped endpoints).
`data`	`object`	Endpoint-specific payload. Most payloads also carry `lastUpdateId`, `requestedUpdateId`, and `ttl`.

`data` envelope extras

Many endpoints share these helper fields inside data:

{
  "lastUpdateId": 5677082919,
  "requestedUpdateId": -1,
  "ttl": 30,
  "sports": [],
  "countries": [],
  "competitions": [],
  "competitors": []
}

lastUpdateId lets you skip identical payloads on the next poll by passing ?lastUpdateId=....
ttl is the suggested seconds before re-requesting.
sports / countries / competitions / competitors are denormalized lookups so a single response can render without follow-up calls.

Status groups

statusGroup on every game object summarizes phase:

Value	Meaning
1	Upcoming / not started
2	Postponed / cancelled
3	Live / in progress
4	Ended

statusText is the human label (Scheduled, Halftime, 1st Half, Ended, …) and shortStatusText is the compact form (FT, HT, 1H, LIVE).

Datetimes

All V1 datetimes are ISO 8601 with timezone offset:

2026-04-04T14:15:00+00:00

(V2 uses Unix epoch in startTimestamp — that’s a V2-only convention.)

Errors

Errors come straight from the backend without wrapping, with the matching HTTP status:

{ "success": false, "error": "Game not found", "code": 404 }

HTTP	Cause
400	Bad parameter (e.g. invalid date format)
401	Missing or invalid `x-api-key`
403	Key valid but plan does not cover the endpoint
404	Entity not found
429	Rate limit exceeded — back off and retry
5xx	Upstream issue — pass through to the user verbatim

See Error Handling for retry and backoff guidance.

Cache TTLs

The server caches every response. Public TTLs:

Endpoint family	TTL
Live / current scores	5s
Game detail	10s
Competition games / results	30s
Search	30s
Standings, brackets, stats	60s
News, transfers	60s
Competitions, countries	60s
Sports list	300s

cacheHit: true means you hit cache. To force a fresh request, vary a query param (?_=Date.now()), but please don’t — the cache is what keeps the API fast.

Pagination

Endpoints that paginate return a paging object inside data:

{
  "paging": {
    "previousPage": 0,
    "nextPage": 2,
    "currentPage": 1,
    "totalPages": 6
  }
}

Pass ?page=N (zero-indexed) to advance.

API Reference

Guides

Popular Sports

Team Sports

Racquet & Precision Sports

Specialty Sports

V3 API

V4 Odds API

V6 AiScore API

V1 Legacy

Football V1

Basketball V1

Tennis V1

Hockey V1

Response Format & Status Codes

Envelope

`data` envelope extras

Status groups

Datetimes

Errors

Cache TTLs

​Envelope

​data envelope extras

​Status groups

​Datetimes

​Errors

​Cache TTLs

​Pagination

Envelope

`data` envelope extras

Status groups

Datetimes

Errors

Cache TTLs

Pagination