# GET /v2/leagues/{id}/top-performances

Group: Leagues

Record individual match performances in a league season. For each statistic — in football goals, assists, rating, xG, key passes, saves, top speed, distance covered, …; in basketball points, rebounds, assists, …; in ice hockey points, hits, saves, … — you get up to 10 players, each with the value and the fixture in which it was achieved. Pass category to limit the response to one statistic.

Plans: Requires Pro, Business or Enterprise; a Free or Starter key receives 403 endpoint_not_in_plan.

Note: category takes a per-match statistic key, as found in a lineup player’s statistics (goals, assists, rating, keyPass, successfulDribbles, topSpeed, kilometersCovered, …) — not a season-leaderboard key such as averageRating. Entries keep our data source’s ranking with the best at the top — and for missed penalties, turnovers and errors leading to a goal, the best is the highest count. fixture contains the complete Fixture (teams, score, start). If type is omitted, the season’s default applies (regularSeason for the NBA, NHL, …). These lists exist for football, basketball and ice hockey; a league that has none returns an empty array. Updated daily.

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `id` | path | yes | league id issued by DataSportsAPI, a positive integer |
| `season` | query | yes | season id, as listed by /v2/leagues/{id}/seasons |
| `type` | query | no | overall \| home \| away \| regularSeason \| playoffs. When omitted, the season’s own default applies: overall if the season has it (football), otherwise regularSeason (NBA, NHL, …); meta.type reports the value used |
| `category` | query | no | restricts the response to a single statistic key from the list (e.g. topSpeed) |

## Response

- `data`: `TopPerformancesCategory[]`
- `meta`: season, type (the value actually applied), category (null when every statistic is included), count (how many categories)
- Objects: TopPerformancesCategory (https://datasportsapi.com/markdown/reference.md#topperformancescategory)

## Errors

- 400 bad_request — one of: season missing or invalid; type outside overall, home, away, regularSeason, playoffs; category malformed
- 404 not_found — the season id does not belong to this league

Plus the common errors (https://datasportsapi.com/markdown/docs.md#errors).

## Request

cURL:

```bash
curl -H "Authorization: Bearer sk_live_…" \
    "https://api.datasportsapi.com/v2/leagues/{id}/top-performances?season=…"
```

TypeScript:

```ts
const { data, meta } = await client.leagues.topPerformances(id, { season });
```

Python:

```python
res = client.leagues.top_performances(id, season=season)
```

Go:

```go
res, err := client.Leagues.TopPerformances(ctx, id, &datasportsapi.LeaguesTopPerformancesParams{Season: season})
```

CLI:

```bash
$ dsa leagues top-performances <id> --season <season>
```

## Example response

```json
{ "data": [ { "category": "rating", "performances": [
      { "player": { "id": 3802, "name": "Bruno Fernandes", "image": "…", … },
        "fixture": { "id": 701102, "home": { "name": "Manchester United", … }, "away": { "name": "Ipswich Town", … },
                     "homeScore": { "current": 5, … }, "awayScore": { "current": 2, … }, "status": { "type": "finished", … }, … },
        "value": 10 }, … ] },
    { "category": "topSpeed", "performances": [ { "player": { "name": "Harvey Barnes", … }, "fixture": { … }, "value": 36.207 }, … ] }, … ],
  "meta": { "season": 200386, "type": "overall", "category": null, "count": 21 } }
```

---

Base URL: https://api.datasportsapi.com. Authenticate each /v2 call with the header `Authorization: Bearer <key>` (secret keys begin with `sk_live_`).
HTML: https://datasportsapi.com/docs/leagues/top-performances/ · All docs: https://datasportsapi.com/markdown/docs.md · Data reference: https://datasportsapi.com/markdown/reference.md
