---
title: "Cricket player career profile"
method: GET
path: "/v1/cricket/players/{id}"
tags: ["cricket"]
---

# Cricket player career profile

`GET /v1/cricket/players/{id}`

## Request

- Base URL: `https://api.bigballsdata.com`
- URL: `https://api.bigballsdata.com/v1/cricket/players/{id}`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Career batting and bowling for one cricket player, aggregated from the stored scorecards (12,559 players; 421,654 batting and 293,284 bowling innings). `batting` / `bowling` are the career totals; `by_format` breaks the same numbers down by match format (Test, ODI, T20, IT20, MDM, ODM) and always sums back to the career line. Derived rates are null rather than 0 when undefined: no dismissals means no batting average, no wickets means no bowling average or best figures. An id with no cricket innings is a 404, not an empty profile.

## Path parameters

- `id` string, uuid, required: A stored BigBalls id. This is the identifier every match, team, player and league endpoint returns, and the one every `{id}` path segment accepts. Take it from the `id` field of the corresponding list endpoint and use it as-is.

## Response `200`

ok. Career profile aggregated from stored scorecard rows.

- object: The standard response wrapper. Only `data` is guaranteed. `error` is absent (not null) on 16 of 40 live 200 responses measured 2026-09-18, so test for the KEY before reading it; this block declared it required until then. On a non-2xx, `error` is present and `data` is absent.
  - `data` object, required
    - `id` string, uuid: A stored BigBalls id. This is the identifier every match, team, player and league endpoint returns, and the one every `{id}` path segment accepts. Take it from the `id` field of the corresponding list endpoint and use it as-is.
    - `name` string, nullable
    - `sport` 'cricket'
    - `nationality` string, nullable
    - `dob` string, date, nullable
    - `team` object, nullable
      - `id` string, uuid: A stored BigBalls id. This is the identifier every match, team, player and league endpoint returns, and the one every `{id}` path segment accepts. Take it from the `id` field of the corresponding list endpoint and use it as-is.
      - `name` string, nullable
    - `career` object
      - `matches` integer: Distinct matches batted or bowled in.
      - `first_match` string, date-time, nullable
      - `last_match` string, date-time, nullable
      - `formats` string[]
    - `batting` CricketBattingCareer
      - `innings` integer, required
      - `not_outs` integer, required: Innings ended undismissed (includes retired hurt / retired not out).
      - `runs` integer, required
      - `balls_faced` integer, required
      - `average` number, nullable: runs / dismissals. null when never dismissed.
      - `strike_rate` number, nullable: Runs per 100 balls. null when no balls faced are recorded.
      - `highest_score` integer, nullable
      - `highest_score_not_out` boolean, nullable: The asterisk in cricket's `254*`.
      - `fifties` integer, required: Scores of 50–99. A hundred counts only in `hundreds`.
      - `hundreds` integer, required
      - `ducks` integer, required: Dismissed for 0.
      - `fours` integer, required
      - `sixes` integer, required
    - `bowling` CricketBowlingCareer
      - `innings` integer, required
      - `overs` string, nullable: Cricket notation, e.g. "206.4" (206 overs and 4 balls). Derived from balls_bowled.
      - `balls_bowled` integer, required
      - `maidens` integer, required
      - `runs_conceded` integer, required
      - `wickets` integer, required
      - `average` number, nullable: runs conceded / wickets. null when wicketless.
      - `economy` number, nullable: Runs conceded per over. null when no balls bowled.
      - `strike_rate` number, nullable: Balls per wicket. null when wicketless.
      - `best_bowling` string, nullable: Best innings figures as wickets/runs, e.g. "5/23". null when wicketless.
    - `by_format` object[]
      - `format` string: Match format: Test, ODI, T20, IT20, MDM, ODM.
      - `batting` CricketBattingCareer
        - `innings` integer, required
        - `not_outs` integer, required: Innings ended undismissed (includes retired hurt / retired not out).
        - `runs` integer, required
        - `balls_faced` integer, required
        - `average` number, nullable: runs / dismissals. null when never dismissed.
        - `strike_rate` number, nullable: Runs per 100 balls. null when no balls faced are recorded.
        - `highest_score` integer, nullable
        - `highest_score_not_out` boolean, nullable: The asterisk in cricket's `254*`.
        - `fifties` integer, required: Scores of 50–99. A hundred counts only in `hundreds`.
        - `hundreds` integer, required
        - `ducks` integer, required: Dismissed for 0.
        - `fours` integer, required
        - `sixes` integer, required
      - `bowling` CricketBowlingCareer
        - `innings` integer, required
        - `overs` string, nullable: Cricket notation, e.g. "206.4" (206 overs and 4 balls). Derived from balls_bowled.
        - `balls_bowled` integer, required
        - `maidens` integer, required
        - `runs_conceded` integer, required
        - `wickets` integer, required
        - `average` number, nullable: runs conceded / wickets. null when wicketless.
        - `economy` number, nullable: Runs conceded per over. null when no balls bowled.
        - `strike_rate` number, nullable: Balls per wicket. null when wicketless.
        - `best_bowling` string, nullable: Best innings figures as wickets/runs, e.g. "5/23". null when wicketless.
  - `meta` ResponseMeta: Response metadata. NOTHING here is guaranteed: measured over 38 live envelopes on 2026-09-18, `cached` and `request_id` appeared in 29, `source` in 28, `cache_age_ms` in 9 and `confidence` in 6. This block previously declared all five REQUIRED, which no response has ever satisfied. Treat every field as optional and branch on its absence. Routes add their own keys here (`count`, `limit`, `offset`, `note`, `total`, and per-endpoint ones), so do not assume a closed set.
    - `date_window` object: Present when ?date= was applied. The exact window the filter used, so an omission at a day boundary is visible. start_utc is inclusive, end_utc exclusive. timezone is UTC, or the zone named by ?tz=, in which case the window is that local day. Boxing card dates are published event dates, so timezone and bounds are null there.
      - `date` string
      - `timezone` string, nullable
      - `start_utc` string, date-time, nullable
      - `end_utc` string, date-time, nullable
      - `note` string
    - `source` 'official-league' | 'aggregator-paid' | 'aggregator-free' | 'community-scraper' | 'forecast' | 'mixed' | 'cache' | 'none' | 'unknown-source' | 'stored' | 'catalogue' | 'gateway' | 'coverage-snapshot': Opaque source-tier label. Customers never see the vendor identity. `forecast` marks a weather forecast (GET /v1/matches/{id}/weather).
    - `confidence` number, float
    - `cached` boolean
    - `cache_age_ms` integer
    - `request_id` string
    - `fields_missing` string[]
    - `note` string: Short factual disclosure about something this response deliberately withheld, present only when there is something to disclose. On live scores it appears when `match_id` could not be resolved to a stored match and was therefore omitted: it gives the counts and points at `/v1/stored/matches`, whose ids you can call back into. Absent when every served id resolves. Distinct from `message`, which explains `coverage: false` or a stale response. This one is attached to a response that DID serve data and names the part of it that is deliberately missing.
  - `error` ApiError
    - `code` string, required
    - `message` string, required
    - `details` unknown

## Other responses

- `400`: The path id is not a Big Balls player UUID.
- `404`: No cricket innings for this id. Distinguishes an id we hold in another sport (fetch it from GET /v1/players/{id}) from one we have never seen.

---

[API](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api.md) · [All operations](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/llms.txt) · [OpenAPI document](https://skmtc.dev/bigballsdata/apis/big-ball-sports-api/revisions/31fb54ac414e?raw)