---
name: datasportapi
description: Use when a task needs sports data (live scores, fixtures, results, line-ups, racecards, standings, players, history) for football, horse or greyhound racing, cricket, basketball, rugby, darts, boxing, volleyball, table tennis, badminton, tennis, ice hockey, baseball, cycling or handball, through the DataSportAPI REST API.
---

# DataSportAPI

## Calling it

- GET https://api.datasportapi.com/v1/{sport}/{endpoint}, key in `X-API-Key` (or `Authorization: Bearer`). Keys start `ds_live_`; one key per account follows its plan.
- Answers are `{data, meta}`. meta: sport, endpoint, count, page/per_page/total/next_cursor when paged, as_of, cached, age_seconds, and access on the free key.
- Ids are ours: two letters for the sport, `_`, ten characters. Take them from one answer and send them to the next. An id only works in its own sport.
- Dates are YYYY-MM-DD in UTC. Leave `date` out of results for yesterday.

## Plans and limits

- Free key: yesterday only, no live or fixtures, 50 calls a day, 10 a minute.
- A sport plan: that sport in full, 120 a minute, 250,000 a month per sport. Complete: every sport, 240 a minute, 1,000,000 a month.
- Headers: X-Rate-Remaining, X-Quota-Used. On 429 wait Retry-After.

## MCP

Server: https://datasportapi.com/mcp (JSON-RPC over POST, key in X-API-Key). Tools: list_sports, live_scores, fixtures, results, racecards_today, get_match, match_detail, competitions, standings, team, player, racing_profile, head_to_head, search. Every tool takes `sport`.

## Errors

Retry `rate`, `upstream` and `server` after Retry-After. Never retry `not_held`, `bad_param`, `not_found` or `plan`: read `detail` and change the call.

## Good habits

- Ask a list, then follow its ids. Do not guess ids.
- Finished results never change: keep them. Live is kept 10 s our side; ask every 10 to 15 s at most.
- Use `/search?q=` to find an id by name.

## Endpoints

- Football `/v1/football`: `/live`, `/fixtures`, `/results`, `/events/{id}` (id), `/events/{id}/lineups` (id), `/events/{id}/periods` (id), `/competitions`, `/standings` (competition, season), `/teams/{id}` (id), `/players/{id}` (id), `/head-to-head` (team, opponent), `/search`
- Horses `/v1/horses`: `/cards/today`, `/cards/upcoming`, `/results`, `/races/{id}` (id), `/horses/{id}/form` (id), `/jockeys/{id}` (id), `/trainers/{id}` (id), `/courses`, `/search`
- Greyhounds `/v1/greyhounds`: `/cards/today`, `/results`, `/races/{id}` (id), `/dogs/{id}/form` (id), `/trainers/{id}` (id), `/tracks`, `/tracks/{id}/stats` (id), `/search`
- Tennis: being connected.
- Cricket `/v1/cricket`: `/live`, `/fixtures`, `/results`, `/matches/{id}` (id), `/matches/{id}/scorecard` (id), `/matches/{id}/deliveries` (id), `/competitions`, `/players/{id}` (id), `/search`
- Basketball `/v1/basketball`: `/live`, `/fixtures`, `/results`, `/events/{id}` (id), `/events/{id}/lineups` (id), `/events/{id}/periods` (id), `/competitions`, `/standings` (competition), `/teams/{id}` (id), `/players/{id}` (id), `/head-to-head` (team, opponent), `/search`
- Ice hockey: being connected.
- Baseball: being connected.
- Rugby `/v1/rugby`: `/live`, `/fixtures`, `/results`, `/events/{id}` (id), `/events/{id}/lineups` (id), `/events/{id}/periods` (id), `/competitions`, `/standings` (season), `/teams/{id}` (id), `/players/{id}` (id), `/head-to-head` (team, opponent), `/search`
- Darts `/v1/darts`: `/live`, `/fixtures`, `/results`, `/matches/{id}` (id), `/matches/{id}/stats` (id), `/tournaments`, `/rankings`, `/players/{id}` (id), `/head-to-head` (player, opponent), `/search`
- Boxing `/v1/boxing`: `/fights/upcoming`, `/results`, `/bouts/{id}` (id), `/bouts/{id}/cards` (id), `/fighters/{id}` (id), `/rankings`, `/search`
- Cycling: being connected.
- Volleyball `/v1/volleyball`: `/live`, `/fixtures`, `/results`, `/events/{id}` (id), `/events/{id}/lineups` (id), `/events/{id}/periods` (id), `/competitions`, `/standings` (competition), `/teams/{id}` (id), `/players/{id}` (id), `/head-to-head` (team, opponent), `/search`
- Handball: being connected.
- Table tennis `/v1/table-tennis`: `/live`, `/fixtures`, `/results`, `/matches/{id}` (id), `/matches/{id}/stats` (id), `/tournaments`, `/players/{id}` (id), `/head-to-head` (player, opponent), `/search`
- Badminton `/v1/badminton`: `/live`, `/fixtures`, `/results`, `/matches/{id}` (id), `/matches/{id}/stats` (id), `/tournaments`, `/rankings`, `/players/{id}` (id), `/head-to-head` (player, opponent), `/search`

Full manual: https://datasportapi.com/documentation/manual.md