# Cricket Database complete reference

The whole Cricket Database API in one file: every endpoint, parameter, sample response and guide.

- Base address: https://api.cricketdatabase.com/v1
- Authentication: your key as `Authorization: Bearer <key>` or `X-API-Key: <key>`; a key in the address is refused
- Site: https://cricketdatabase.com/
- Endpoints: 47
- Generated: 10 October 2026, 08:59 UTC (from the newest change to its sources)
- This file: https://cricketdatabase.com/documentation/manual.md

## Before anything else

- Factual data only: results, scorecards, every ball, players, teams, grounds and figures counted from them. No predictions, ratings, tips or betting advice on any endpoint.
- Not in the dataset, on any plan, at any price: betting odds; pitch reports and attendance; ball by ball before December 2001; on scorecards before 2001, the fielder and the bowler for each dismissal; player photographs.
- Every answer is `{"data": ..., "meta": {...}}`. `meta` carries the plan the key is on, and for a list `count`, `page`, `per_page`, `total`, `total_pages`, `next_page`, `prev_page` and `next_cursor`. A failure is `{"error": {"code", "message", "docs"}}`.

## Plans

| Plan | Price | What it reads | Rate limit | Calls a day |
|---|---|---|---|---|
| Free key | Free | The last 30 days in full, samples of older matches | 10 a minute | 50 |
| Match Week | $49 a month | Live matches and the last 7 days ball by ball | 60 a minute | 5,000 |
| Archive | $69 a month | Every match to yesterday | 120 a minute | 25,000 |
| Pro | $99 a month | Every match, and live | 180 a minute | 50,000 |
| Analyst Pro | $149 a month | Everything, with splits, matchups and trends | 300 a minute | 100,000 |

Paid plans are also sold yearly, for the price of ten months. Card charges appear as DEVELOPERDATA.NET.

## Coverage

Counted from the data at the last update, the same figures `GET /v1/status` returns:

- 23,855 matches held ball by ball
- 11,985,023 deliveries
- 19,425 players and officials
- 1,185 competitions
- Every men's and women's Test, ODI and T20 international back to 1877 listed, each with its scorecard, its innings totals or its result (`coverage`)

## Endpoints

### Account and reference

#### `GET /v1/usage`

Calls today, the daily limit, when it resets, and which plan the key is on.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/usage`

```json
{
    "data": {
        "plan": "plus",
        "plan_name": "Analyst Pro",
        "calls": {
            "today": 0,
            "this_month": 0
        },
        "limits": {
            "per_day": 100000,
            "per_minute": 300,
            "remaining_today": 100000
        },
        "resets": {
            "day": "2026-10-13T00:00:00Z",
            "minute": "2026-10-12T12:11:00Z"
        },
        "key": {
            "prefix": "cdb_live_doc",
            "label": "Documentation",
            "created_at": "2026-10-12T12:10:58Z",
            "last_used_at": null
        }
    },
    "meta": {
        "plan": "plus",
        "window": {
            "from": "2001-12-01",
            "to": "today",
            "ball_by_ball": "every match",
            "analytics": true
        }
    }
}
```

Page: https://cricketdatabase.com/documentation/usage

#### `GET /v1/status`

The latest update, match, delivery and people counts. No key needed; use it as a health check.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/status`

```json
{
    "data": {
        "ok": true,
        "matches": 23855,
        "deliveries": 11985023,
        "people": 19425,
        "competitions": 1185,
        "latest_update": "2026-10-12T10:15:06Z",
        "latest_match": "2026-10-11"
    },
    "meta": []
}
```

Page: https://cricketdatabase.com/documentation/status

#### `GET /v1/search`

Players, teams, venues and competitions by name, including the other names a player has been recorded under.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `q` | query | text | yes | At least 2 characters | `root` |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/search?q=root`

```json
{
    "data": {
        "q": "root",
        "players": [
            {
                "player": "je-root",
                "name": "JE Root",
                "matches": 516
            },
            {
                "player": "wt-root",
                "name": "WT Root",
                "matches": 184
            },
            "... 1 more"
        ],
        "teams": [],
        "venues": [],
        "competitions": []
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/search

### Matches

#### `GET /v1/matches`

Matches, newest first, filtered and paged: ball by ball from December 2001, and every men's Test, ODI and T20 international back to 1877 with its scorecard (coverage scorecard), its innings totals (coverage totals) or its result (coverage result_only). The free key and Match Week see the last 30 days.

Plans: Free key (last 30 days), Match Week (last 30 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `date` | query | date | no | One day, YYYY-MM-DD |  |
| `from` | query | date | no | On or after |  |
| `to` | query | date | no | On or before |  |
| `year` | query | int | no | A calendar year | `2025` |
| `month` | query | int | no | With year, 1 to 12 |  |
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day | `test` |
| `gender` | query | text | no | male or female |  |
| `team` | query | team address | no |  |  |
| `venue` | query | venue address | no |  |  |
| `competition` | query | competition address | no |  |  |
| `coverage` | query | text | no | full (ball by ball, with its scorecard), scorecard (each batter's and bowler's line, no balls), totals (innings totals, extras and fall of wickets) or result_only |  |
| `page` | query | int | no | Page number, from 1 |  |
| `limit` | query | int | no | Results per page, 1 to 100 (default 50) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/matches?format=test&year=2025`

```json
{
    "data": [
        {
            "match": "2025-12-26-australia-v-england",
            "date": "2025-12-26",
            "format": "test",
            "gender": "male",
            "coverage": "full",
            "competition": "The Ashes",
            "stage": "Match 4",
            "ground": null,
            "official_number": null,
            "teams": [
                {
                    "team": "australia",
                    "name": "Australia",
                    "score": "152 & 132",
                    "overs": "34.3",
                    "won": false
                },
                {
                    "team": "england",
                    "name": "England",
                    "score": "110 & 178/6",
                    "overs": "32.2",
                    "won": true
                }
            ],
            "result": "England won by 4 wickets"
        },
        {
            "match": "2025-12-18-new-zealand-v-west-indies",
            "date": "2025-12-18",
            "format": "test",
            "gender": "male",
            "coverage": "full",
            "competition": "West Indies tour of New Zealand",
            "stage": "Match 3",
            "ground": null,
            "official_number": null,
            "teams": [
                {
                    "team": "new-zealand",
                    "name": "New Zealand",
                    "score": "575/8d & 306/2d",
                    "overs": "54",
                    "won": true
                },
                {
                    "team": "west-indies",
                    "name": "West Indies",
                    "score": "420 & 138",
                    "overs": "80.3",
                    "won": false
                }
            ],
            "result": "New Zealand won by 323 runs"
        },
        "... 1 more"
    ],
    "meta": {
        "plan": "plus",
        "count": 43,
        "next_cursor": null,
        "page": 1,
        "per_page": 50,
        "total": 43,
        "total_pages": 1,
        "next_page": null,
        "prev_page": null
    }
}
```

Page: https://cricketdatabase.com/documentation/matches

#### `GET /v1/matches/{match}`

One match: teams, result, toss, venue, officials, player of the match and the innings totals. An international held without its balls answers coverage scorecard or totals, with each innings, its extras and fall of wickets, or result_only. Older than 30 days on the free key comes back as a summary.

Plans: Free key (last 30 days), Match Week (last 30 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/matches/2026-09-17-sri-lanka-v-england`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "date": "2026-09-17",
        "end_date": "2026-09-17",
        "format": "t20i",
        "gender": "male",
        "teams": [
            {
                "team": "sri-lanka",
                "name": "Sri Lanka"
            },
            {
                "team": "england",
                "name": "England"
            }
        ],
        "result": "England won by 6 wickets",
        "coverage": "full",
        "competition": {
            "competition": "sri-lanka-tour-of-england",
            "name": "Sri Lanka tour of England"
        },
        "season": "2026",
        "stage": "Match 2",
        "official_number": 4129,
        "venue": {
            "venue": "sophia-gardens",
            "name": "Sophia Gardens",
            "city": "Cardiff"
        },
        "toss": "England, chose to field",
        "rain_rule": null,
        "innings": [
            {
                "team": "sri-lanka",
                "runs": 145,
                "wickets": 9,
                "overs": "20",
                "innings_declared": false,
                "is_super_over": false,
                "chase_target": null
            },
            {
                "team": "england",
                "runs": 146,
                "wickets": 4,
                "overs": "12.1",
                "innings_declared": false,
                "is_super_over": false,
                "chase_target": 146
            }
        ],
        "player_of_the_match": [
            {
                "player": "la-dawson",
                "name": "LA Dawson"
            }
        ],
        "officials": {
            "on_field_umpires": [
                "RJ Warren",
                "Rob White"
            ],
            "third_umpire": [
                "GD Lloyd"
            ],
            "fourth_umpire": [
                "James Middlebrook"
            ],
            "referee": [
                "JJ Crowe"
            ]
        }
    },
    "meta": {
        "plan": "plus",
        "detail": "full"
    }
}
```

Page: https://cricketdatabase.com/documentation/match

#### `GET /v1/matches/{match}/scorecard`

Every innings: batting with dismissals, bowling, extras, did not bat and fall of wickets, and weather: each day's highest and lowest temperature, rain, humidity, dew point and wind at the ground.

Plans: Free key (last 30 days), Match Week (last 30 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/matches/2026-09-17-sri-lanka-v-england/scorecard`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "result": "England won by 6 wickets",
        "innings": [
            {
                "innings": 1,
                "team": "sri-lanka",
                "name": "Sri Lanka",
                "runs": 145,
                "wickets": 9,
                "overs": "20",
                "run_rate": 7.25,
                "extras": 9,
                "extras_detail": "b 5, lb 1, w 3",
                "is_super_over": false,
                "batting": [
                    {
                        "player": "p-nissanka",
                        "name": "P Nissanka",
                        "dismissal": "c HC Brook b J Overton",
                        "out": true,
                        "runs": 37,
                        "balls": 21,
                        "fours": 4,
                        "sixes": 1
                    },
                    {
                        "player": "lu-igalagamage",
                        "name": "LU Igalagamage",
                        "dismissal": "c J Overton b LA Dawson",
                        "out": true,
                        "runs": 21,
                        "balls": 20,
                        "fours": 5,
                        "sixes": 0
                    },
                    "... 1 more"
                ],
                "did_not_bat": [
                    {
                        "player": "d-madushanka",
                        "name": "D Madushanka"
                    }
                ],
                "fall_of_wickets": [
                    {
                        "wicket": 1,
                        "runs": 56,
                        "player": "LU Igalagamage"
                    },
                    {
                        "wicket": 2,
                        "runs": 56,
                        "player": "K Mishara"
                    },
                    "... 1 more"
                ],
                "bowling": [
                    {
                        "player": "s-baker",
                        "name": "S Baker",
                        "overs": "4",
                        "maidens": 1,
                        "runs": 15,
                        "wickets": 1,
                        "economy": "3.75",
                        "dots": 14,
                        "fours": 2,
                        "sixes": 0,
                        "wides": 0,
                        "no_balls": 0
                    },
                    {
                        "player": "jc-archer",
                        "name": "JC Archer",
                        "overs": "4",
                        "maidens": 0,
                        "runs": 34,
                        "wickets": 2,
                        "economy": "8.50",
                        "dots": 9,
                        "fours": 6,
                        "sixes": 0,
                        "wides": 0,
                        "no_balls": 0
                    },
                    "... 1 more"
                ]
            },
            {
                "innings": 2,
                "team": "england",
                "name": "England",
                "runs": 146,
                "wickets": 4,
                "overs": "12.1",
                "run_rate": 12,
                "extras": 5,
                "extras_detail": "lb 1, w 3, nb 1",
                "is_super_over": false,
                "batting": [
                    {
                        "player": "jc-buttler",
                        "name": "JC Buttler",
                        "dismissal": "c K Mishara b PVD Chameera",
                        "out": true,
                        "runs": 30,
                        "balls": 16,
                        "fours": 4,
                        "sixes": 1
                    },
                    {
                        "player": "aht-donald",
                        "name": "AHT Donald",
                        "dismissal": "c PWH de Silva b E Malinga",
                        "out": true,
                        "runs": 21,
                        "balls": 13,
                        "fours": 2,
                        "sixes": 1
                    },
                    "... 1 more"
                ],
                "did_not_bat": [
                    {
                        "player": "j-overton",
                        "name": "J Overton"
                    },
                    {
                        "player": "la-dawson",
                        "name": "LA Dawson"
                    },
                    "... 1 more"
                ],
                "fall_of_wickets": [
                    {
                        "wicket": 1,
                        "runs": 51,
                        "player": "AHT Donald"
                    },
                    {
                        "wicket": 2,
                        "runs": 55,
                        "player": "JC Buttler"
                    },
                    "... 1 more"
                ],
                "bowling": [
                    {
                        "player": "d-madushanka",
                        "name": "D Madushanka",
                        "overs": "2",
                        "maidens": 0,
                        "runs": 22,
                        "wickets": 0,
                        "economy": "11.00",
                        "dots": 3,
                        "fours": 4,
                        "sixes": 0,
                        "wides": 0,
                        "no_balls": 0
                    },
                    {
                        "player": "pvd-chameera",
                        "name": "PVD Chameera",
                        "overs": "3",
                        "maidens": 0,
                        "runs": 29,
                        "wickets": 1,
                        "economy": "9.67",
                        "dots": 5,
                        "fours": 2,
                        "sixes": 1,
                        "wides": 1,
                        "no_balls": 1
                    },
                    "... 1 more"
                ]
            }
        ],
        "weather": [
            {
                "day": "2026-09-17",
                "max_c": 17.1,
                "min_c": 12.4,
                "rain_mm": 2.8,
                "humidity_pct": 80,
                "dew_point_c": 11,
                "wind_kmh": 16
            }
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/scorecard

#### `GET /v1/matches/{match}/deliveries`

Every ball, with batter, non-striker, bowler, runs, extras and wickets. Match Week reads the last 7 days, Archive everything to yesterday, Pro and Analyst Pro everything. Players come once in a dictionary; balls carry their addresses.

Plans: Free key (sample), Match Week (last 7 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/matches/2026-09-17-sri-lanka-v-england/deliveries`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "count": 200,
        "players": {
            "p-nissanka": "P Nissanka",
            "lu-igalagamage": "LU Igalagamage",
            "s-baker": "S Baker",
            "jc-archer": "JC Archer",
            "wg-jacks": "WG Jacks",
            "la-dawson": "LA Dawson",
            "k-mishara": "K Mishara",
            "kic-asalanka": "KIC Asalanka",
            "j-overton": "J Overton",
            "phkd-mendis": "PHKD Mendis",
            "au-rashid": "AU Rashid",
            "md-shanaka": "MD Shanaka",
            "pwh-de-silva": "PWH de Silva",
            "kth-ratnayake": "KTH Ratnayake",
            "pvd-chameera": "PVD Chameera",
            "e-malinga": "E Malinga",
            "jc-buttler": "JC Buttler",
            "aht-donald": "AHT Donald",
            "d-madushanka": "D Madushanka",
            "hc-brook": "HC Brook",
            "t-banton": "T Banton",
            "jm-cox": "JM Cox"
        },
        "deliveries": [
            {
                "innings": 1,
                "over": 1,
                "ball": 1,
                "batter": "p-nissanka",
                "partner": "lu-igalagamage",
                "bowler": "s-baker",
                "runs": {
                    "batter": 2,
                    "extras": 0,
                    "total": 2
                }
            },
            {
                "innings": 1,
                "over": 1,
                "ball": 2,
                "batter": "p-nissanka",
                "partner": "lu-igalagamage",
                "bowler": "s-baker",
                "runs": {
                    "batter": 1,
                    "extras": 0,
                    "total": 1
                }
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus",
        "held_back": 0
    }
}
```

Page: https://cricketdatabase.com/documentation/deliveries

#### `GET /v1/matches/{match}/overs`

Over by over: runs, wickets, extras, the running total and the bowler.

Plans: Match Week (last 7 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/matches/2026-09-17-sri-lanka-v-england/overs`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "overs": [
            {
                "innings": 1,
                "over": 1,
                "runs": 3,
                "wickets": 0,
                "extras": 0,
                "legal_balls": 6,
                "total": 3,
                "bowler": {
                    "player": "s-baker",
                    "name": "S Baker"
                }
            },
            {
                "innings": 1,
                "over": 2,
                "runs": 14,
                "wickets": 0,
                "extras": 0,
                "legal_balls": 6,
                "total": 17,
                "bowler": {
                    "player": "jc-archer",
                    "name": "JC Archer"
                }
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/overs

#### `GET /v1/matches/{match}/partnerships`

Every partnership, worked out from the balls: the pair, runs, balls and how it ended.

Plans: Match Week (last 7 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/matches/2026-09-17-sri-lanka-v-england/partnerships`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "players": {
            "p-nissanka": "P Nissanka",
            "lu-igalagamage": "LU Igalagamage",
            "s-baker": "S Baker",
            "jc-archer": "JC Archer",
            "wg-jacks": "WG Jacks",
            "la-dawson": "LA Dawson",
            "k-mishara": "K Mishara",
            "kic-asalanka": "KIC Asalanka",
            "j-overton": "J Overton",
            "phkd-mendis": "PHKD Mendis",
            "au-rashid": "AU Rashid",
            "md-shanaka": "MD Shanaka",
            "pwh-de-silva": "PWH de Silva",
            "kth-ratnayake": "KTH Ratnayake",
            "pvd-chameera": "PVD Chameera",
            "e-malinga": "E Malinga",
            "jc-buttler": "JC Buttler",
            "aht-donald": "AHT Donald",
            "d-madushanka": "D Madushanka",
            "hc-brook": "HC Brook",
            "t-banton": "T Banton",
            "jm-cox": "JM Cox"
        },
        "partnerships": [
            {
                "innings": 1,
                "wicket": 1,
                "batters": [
                    "lu-igalagamage",
                    "p-nissanka"
                ],
                "runs": 56,
                "balls": 33,
                "ended": "caught, LU Igalagamage"
            },
            {
                "innings": 1,
                "wicket": 2,
                "batters": [
                    "k-mishara",
                    "p-nissanka"
                ],
                "runs": 0,
                "balls": 1,
                "ended": "caught and bowled, K Mishara"
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/partnerships

#### `GET /v1/matches/{match}/reviews`

Every DRS review: the ball, who asked, the batter, the umpire, the decision and umpire's call.

Plans: Match Week (last 7 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/matches/2026-09-17-sri-lanka-v-england/reviews`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "reviews": []
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/reviews

#### `GET /v1/results/yesterday`

Every result from the latest day in the database.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/results/yesterday`

```json
{
    "data": {
        "date": "2026-10-11",
        "count": 4,
        "results": [
            {
                "match": "2026-10-11-kowloon-cricket-club-v-hong-kong-cricket-club",
                "date": "2026-10-11",
                "format": "one-day",
                "gender": "male",
                "coverage": "full",
                "competition": "Hong Kong Premier League One-Day Tournament",
                "stage": "Match 3",
                "ground": null,
                "official_number": null,
                "teams": [
                    {
                        "team": "kowloon-cricket-club",
                        "name": "Kowloon Cricket Club",
                        "score": "320/7",
                        "overs": "50",
                        "won": true
                    },
                    {
                        "team": "hong-kong-cricket-club",
                        "name": "Hong Kong Cricket Club",
                        "score": "185",
                        "overs": "44.2",
                        "won": false
                    }
                ],
                "result": "Kowloon Cricket Club won by 135 runs"
            },
            {
                "match": "2026-10-11-titans-v-easterns",
                "date": "2026-10-11",
                "format": "t20",
                "gender": "male",
                "coverage": "full",
                "competition": "CSA Pro20 Cup",
                "stage": null,
                "ground": null,
                "official_number": null,
                "teams": [
                    {
                        "team": "titans",
                        "name": "Titans",
                        "score": "260/4",
                        "overs": "20",
                        "won": true
                    },
                    {
                        "team": "easterns",
                        "name": "Easterns",
                        "score": "161/7",
                        "overs": "20",
                        "won": false
                    }
                ],
                "result": "Titans won by 99 runs"
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus",
        "count": 4
    }
}
```

Page: https://cricketdatabase.com/documentation/results-yesterday

### Live

#### `GET /v1/live`

Every match in play now, men and women, international and domestic, with the score of each innings and the state of play in words. Updated every minute. state=upcoming lists matches starting in the next 24 hours, finished those of the last 48 hours. ball_by_ball says whether the match has every ball; some domestic matches have the score only.

Plans: Match Week (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `state` | query | text | no | live (the default), upcoming, finished or all | `all` |
| `format` | query | text | no | Test, ODI, T20I, T20, First-class, List A |  |
| `international` | query | text | no | true for Tests, ODIs and T20 internationals only |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/live?state=all`

A live answer changes by the minute; the documentation page runs it live.

Page: https://cricketdatabase.com/documentation/live

#### `GET /v1/live/{match}`

One live match: the score, the batting and bowling of every innings so far, who is in and on strike, the bowler, the partnership, the run rate, the chase (target, runs needed, balls left and required rate) and the last 12 balls as marks (. 1 4 6 W 1wd 2nb 1lb 1b). last_ball is the cursor to pass to the balls endpoint.

Plans: Match Week (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/live/{live}`

A live answer changes by the minute; the documentation page runs it live.

Page: https://cricketdatabase.com/documentation/live-match

#### `GET /v1/live/{match}/balls`

Every ball of a live match in order, with the same fields as deliveries: batter, partner, bowler, runs, extras and wickets. Pass after (the next value of the last answer, or last_ball from the match) to get only the balls bowled since, so a poll every minute costs one call. A ball corrected by the scorers takes the place of the first version.

Plans: Match Week (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `after` | query | text | no | The next value from an earlier answer |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/live/{live}/balls`

A live answer changes by the minute; the documentation page runs it live.

Page: https://cricketdatabase.com/documentation/live-balls

#### `GET /v1/live/stream`

Live scores pushed instead of polled: one connection sends server-sent events as they happen. snapshot on connect (every match in play, as /v1/live gives it), score when a match's score or state changes, and ball for every new ball (as /v1/live/{match}/balls gives it, with its match). match= follows one match only. Send the key in a header as on every call, so read it with any SSE client on a server (curl -N, Python sseclient, Node eventsource). Each event carries an id: a client that reconnects sends it back by itself and carries on with no ball missed or repeated. A connection lasts 2 minutes and the client reconnects by itself; each connection counts as one call, and a key holds up to 2 at once. For the balls already bowled, call /v1/live/{match}/balls once, then follow the stream.

Plans: Match Week (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `match` | query | text | no | A live match address from /v1/live; leave out for every match in play |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/live/stream`

A live answer changes by the minute; the documentation page runs it live.

Page: https://cricketdatabase.com/documentation/live-stream

### Players

#### `GET /v1/players`

Players who have played, most matches first, or matched by name.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `q` | query | text | no | Name, including recorded variants | `kohli` |
| `team` | query | team address | no |  |  |
| `gender` | query | text | no | male or female |  |
| `page` | query | int | no | Page number, from 1 |  |
| `limit` | query | int | no | Results per page, 1 to 100 (default 50) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/players?q=kohli`

```json
{
    "data": [
        {
            "player": "v-kohli",
            "name": "V Kohli",
            "matches": 846
        },
        {
            "player": "a-kohli",
            "name": "A Kohli",
            "matches": 41
        },
        "... 1 more"
    ],
    "meta": {
        "plan": "plus",
        "count": 7,
        "next_cursor": null,
        "page": 1,
        "per_page": 50,
        "total": 7,
        "total_pages": 1,
        "next_page": null,
        "prev_page": null
    }
}
```

Page: https://cricketdatabase.com/documentation/players

#### `GET /v1/players/{player}`

A player: teams with match counts, first and latest match, birth and death details (born, birthplace, died, deathplace, nationality) and playing style (batting_style, bowling_style), each null when not known. Dates are YYYY-MM-DD, or YYYY-MM or YYYY when only that much is known.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/players/je-root`

```json
{
    "data": {
        "player": "je-root",
        "name": "JE Root",
        "gender": "male",
        "country": "England",
        "born": "1990-12-30",
        "birthplace": "Dore",
        "died": null,
        "deathplace": null,
        "nationality": "United Kingdom",
        "batting_style": "Right-hand bat",
        "bowling_style": "Right-arm off-break",
        "first_match": "2012-12-13",
        "latest_match": "2026-09-27",
        "matches": 516,
        "teams": [
            {
                "team": "england",
                "name": "England",
                "matches": 395
            },
            {
                "team": "yorkshire",
                "name": "Yorkshire",
                "matches": 64
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/player

#### `GET /v1/players/{player}/stats`

Career batting and bowling by format.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/players/je-root/stats`

```json
{
    "data": {
        "player": "je-root",
        "name": "JE Root",
        "batting": {
            "test": {
                "matches": 169,
                "innings": 309,
                "not_outs": 26,
                "runs": 14278,
                "high_score": 262,
                "high_score_not_out": false,
                "average": 50.45,
                "balls": 24783,
                "strike_rate": 57.61,
                "hundreds": 41,
                "fifties": 69,
                "fours": 1536,
                "sixes": 46
            },
            "odi": {
                "matches": 184,
                "innings": 184,
                "not_outs": 28,
                "runs": 7903,
                "high_score": 166,
                "high_score_not_out": true,
                "average": 50.66,
                "balls": 9012,
                "strike_rate": 87.69,
                "hundreds": 20,
                "fifties": 48,
                "fours": 645,
                "sixes": 55
            },
            "t20i": {
                "matches": 30,
                "innings": 30,
                "not_outs": 5,
                "runs": 893,
                "high_score": 90,
                "high_score_not_out": true,
                "average": 35.72,
                "balls": 707,
                "strike_rate": 126.31,
                "hundreds": 0,
                "fifties": 5,
                "fours": 92,
                "sixes": 16
            },
            "t20_leagues": {
                "matches": 80,
                "innings": 80,
                "not_outs": 17,
                "runs": 2165,
                "high_score": 92,
                "high_score_not_out": true,
                "average": 34.37,
                "balls": 1634,
                "strike_rate": 132.5,
                "hundreds": 0,
                "fifties": 16,
                "fours": 211,
                "sixes": 44
            },
            "multi-day": {
                "matches": 29,
                "innings": 45,
                "not_outs": 2,
                "runs": 2163,
                "high_score": 213,
                "high_score_not_out": false,
                "average": 50.3,
                "balls": 3313,
                "strike_rate": 65.29,
                "hundreds": 6,
                "fifties": 11,
                "fours": 238,
                "sixes": 5
            },
            "one-day": {
                "matches": 7,
                "innings": 7,
                "not_outs": 1,
                "runs": 304,
                "high_score": 83,
                "high_score_not_out": false,
                "average": 50.67,
                "balls": 380,
                "strike_rate": 80,
                "hundreds": 0,
                "fifties": 3,
                "fours": 23,
                "sixes": 1
            }
        },
        "bowling": {
            "test": {
                "matches": 127,
                "balls": 6332,
                "runs": 3559,
                "wickets": 74,
                "best": "5-8",
                "average": 48.09,
                "economy": 3.37,
                "strike_rate": 85.6,
                "maidens": 165,
                "five_fors": 1
            },
            "odi": {
                "matches": 79,
                "balls": 1788,
                "runs": 1759,
                "wickets": 31,
                "best": "3-52",
                "average": 56.74,
                "economy": 5.9,
                "strike_rate": 57.7,
                "maidens": 2,
                "five_fors": 0
            },
            "t20i": {
                "matches": 9,
                "balls": 84,
                "runs": 139,
                "wickets": 6,
                "best": "2-9",
                "average": 23.17,
                "economy": 9.93,
                "strike_rate": 14,
                "maidens": 0,
                "five_fors": 0
            },
            "t20_leagues": {
                "matches": 36,
                "balls": 537,
                "runs": 688,
                "wickets": 27,
                "best": "2-7",
                "average": 25.48,
                "economy": 7.69,
                "strike_rate": 19.9,
                "maidens": 0,
                "five_fors": 0
            },
            "multi-day": {
                "matches": 25,
                "balls": 1686,
                "runs": 846,
                "wickets": 23,
                "best": "4-5",
                "average": 36.78,
                "economy": 3.01,
                "strike_rate": 73.3,
                "maidens": 46,
                "five_fors": 0
            },
            "one-day": {
                "matches": 2,
                "balls": 54,
                "runs": 58,
                "wickets": 0,
                "best": null,
                "average": null,
                "economy": 6.44,
                "strike_rate": null,
                "maidens": 0,
                "five_fors": 0
            }
        },
        "splits": null
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/player-stats

#### `GET /v1/players/{player}/innings`

Every batting innings, newest first. Lower plans get the last ten.

Plans: Free key (sample), Match Week (sample), Archive (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |
| `year` | query | int | no |  |  |
| `page` | query | int | no | Page number, from 1 |  |
| `limit` | query | int | no | Results per page, 1 to 100 (default 50) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/players/je-root/innings`

```json
{
    "data": [
        {
            "match": "2026-09-27-england-v-sri-lanka",
            "date": "2026-09-27",
            "format": "odi",
            "team": "England",
            "opponent": "Sri Lanka",
            "innings": 1,
            "runs": 18,
            "balls": 37,
            "fours": 1,
            "sixes": 0,
            "out": true,
            "how_out": "lbw"
        },
        {
            "match": "2026-09-24-sri-lanka-v-england",
            "date": "2026-09-24",
            "format": "odi",
            "team": "England",
            "opponent": "Sri Lanka",
            "innings": 2,
            "runs": 15,
            "balls": 17,
            "fours": 1,
            "sixes": 0,
            "out": true,
            "how_out": "caught"
        },
        "... 1 more"
    ],
    "meta": {
        "plan": "plus",
        "count": 50,
        "next_cursor": "Y2RiOnAy",
        "page": 1,
        "per_page": 50,
        "total": 655,
        "total_pages": 14,
        "next_page": 2,
        "prev_page": null,
        "player": "je-root"
    }
}
```

Page: https://cricketdatabase.com/documentation/player-innings

#### `GET /v1/players/{player}/bowling`

Every bowling spell, newest first. Lower plans get the last ten.

Plans: Free key (sample), Match Week (sample), Archive (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |
| `year` | query | int | no |  |  |
| `page` | query | int | no | Page number, from 1 |  |
| `limit` | query | int | no | Results per page, 1 to 100 (default 50) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/players/je-root/bowling`

```json
{
    "data": [
        {
            "match": "2026-09-27-england-v-sri-lanka",
            "date": "2026-09-27",
            "format": "odi",
            "team": "England",
            "opponent": "Sri Lanka",
            "innings": 2,
            "overs": "3",
            "maidens": 0,
            "runs": 15,
            "wickets": 1,
            "dots": 11
        },
        {
            "match": "2026-07-25-welsh-fire-v-mi-london",
            "date": "2026-07-25",
            "format": "t20",
            "team": "Welsh Fire",
            "opponent": "MI London",
            "innings": 2,
            "overs": "1",
            "maidens": 0,
            "runs": 10,
            "wickets": 0,
            "dots": 1
        },
        "... 1 more"
    ],
    "meta": {
        "plan": "plus",
        "count": 50,
        "next_cursor": "Y2RiOnAy",
        "page": 1,
        "per_page": 50,
        "total": 331,
        "total_pages": 7,
        "next_page": 2,
        "prev_page": null,
        "player": "je-root"
    }
}
```

Page: https://cricketdatabase.com/documentation/player-bowling

### Teams

#### `GET /v1/teams`

Every team, international or club, with match counts.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/teams`

```json
{
    "data": {
        "total": 428,
        "data": [
            {
                "team": "india",
                "name": "India",
                "type": "international",
                "matches": 1409
            },
            {
                "team": "england",
                "name": "England",
                "type": "international",
                "matches": 1345
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/teams

#### `GET /v1/teams/{team}`

A team: record by format, main competitions and most-capped players.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/teams/england`

```json
{
    "data": {
        "team": "england",
        "name": "England",
        "first_match": "2001-12-19",
        "latest_match": "2026-09-27",
        "record": {
            "odi": {
                "played": 620,
                "won": 337,
                "lost": 252
            },
            "t20i": {
                "played": 424,
                "won": 267,
                "lost": 140
            },
            "test": {
                "played": 301,
                "won": 131,
                "lost": 106
            }
        },
        "competitions": [
            {
                "competition": "natwest-series",
                "name": "NatWest Series",
                "matches": 93
            },
            {
                "competition": "mens-t20-world-cup",
                "name": "ICC Men's T20 World Cup",
                "matches": 57
            },
            "... 1 more"
        ],
        "most_matches": [
            {
                "player": "jc-buttler",
                "name": "JC Buttler",
                "matches": 424
            },
            {
                "player": "je-root",
                "name": "JE Root",
                "matches": 395
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/team

#### `GET /v1/teams/{team}/matches`

A team's matches, with every filter of /v1/matches.

Plans: Free key (last 30 days), Match Week (last 30 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `date` | query | date | no | One day, YYYY-MM-DD |  |
| `from` | query | date | no | On or after |  |
| `to` | query | date | no | On or before |  |
| `year` | query | int | no | A calendar year |  |
| `month` | query | int | no | With year, 1 to 12 |  |
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |
| `gender` | query | text | no | male or female |  |
| `page` | query | int | no | Page number, from 1 |  |
| `limit` | query | int | no | Results per page, 1 to 100 (default 50) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/teams/england/matches`

```json
{
    "data": [
        {
            "match": "2026-09-27-england-v-sri-lanka",
            "date": "2026-09-27",
            "format": "odi",
            "gender": "male",
            "coverage": "full",
            "competition": "Sri Lanka tour of England",
            "stage": "Match 3",
            "ground": null,
            "official_number": null,
            "teams": [
                {
                    "team": "england",
                    "name": "England",
                    "score": "355/7",
                    "overs": "50",
                    "won": true
                },
                {
                    "team": "sri-lanka",
                    "name": "Sri Lanka",
                    "score": "132",
                    "overs": "29.1",
                    "won": false
                }
            ],
            "result": "England won by 223 runs"
        },
        {
            "match": "2026-09-24-sri-lanka-v-england",
            "date": "2026-09-24",
            "format": "odi",
            "gender": "male",
            "coverage": "full",
            "competition": "Sri Lanka tour of England",
            "stage": "Match 2",
            "ground": null,
            "official_number": null,
            "teams": [
                {
                    "team": "sri-lanka",
                    "name": "Sri Lanka",
                    "score": "321/6",
                    "overs": "50",
                    "won": true
                },
                {
                    "team": "england",
                    "name": "England",
                    "score": "305/9",
                    "overs": "50",
                    "won": false
                }
            ],
            "result": "Sri Lanka won by 16 runs"
        },
        "... 1 more"
    ],
    "meta": {
        "plan": "plus",
        "count": 50,
        "next_cursor": "Y2RiOnAy",
        "page": 1,
        "per_page": 50,
        "total": 2926,
        "total_pages": 59,
        "next_page": 2,
        "prev_page": null
    }
}
```

Page: https://cricketdatabase.com/documentation/team-matches

#### `GET /v1/teams/{team}/head-to-head/{other}`

Two teams against each other, by format, with the last ten meetings.

Plans: Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/teams/england/head-to-head/australia`

```json
{
    "data": {
        "teams": [
            "england",
            "australia"
        ],
        "by_format": {
            "odi": {
                "played": 119,
                "england": 43,
                "australia": 73,
                "other": 3
            },
            "t20i": {
                "played": 65,
                "england": 28,
                "australia": 32,
                "other": 5
            },
            "test": {
                "played": 73,
                "england": 21,
                "australia": 36,
                "other": 16
            }
        },
        "recent": [
            {
                "match": "2026-07-05-england-v-australia-women",
                "date": "2026-07-05",
                "format": "t20i",
                "gender": "female",
                "coverage": "full",
                "competition": "ICC Women's T20 World Cup",
                "stage": "Final",
                "ground": null,
                "official_number": null,
                "teams": [
                    {
                        "team": "england",
                        "name": "England",
                        "score": "150/4",
                        "overs": "20",
                        "won": false
                    },
                    {
                        "team": "australia",
                        "name": "Australia",
                        "score": "153/3",
                        "overs": "17.1",
                        "won": true
                    }
                ],
                "result": "Australia won by 7 wickets"
            },
            {
                "match": "2026-01-04-england-v-australia",
                "date": "2026-01-04",
                "format": "test",
                "gender": "male",
                "coverage": "full",
                "competition": "The Ashes",
                "stage": "Match 5",
                "ground": null,
                "official_number": null,
                "teams": [
                    {
                        "team": "england",
                        "name": "England",
                        "score": "384 & 342",
                        "overs": "88.2",
                        "won": false
                    },
                    {
                        "team": "australia",
                        "name": "Australia",
                        "score": "567 & 161/5",
                        "overs": "31.2",
                        "won": true
                    }
                ],
                "result": "Australia won by 5 wickets"
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/head-to-head

### Venues

#### `GET /v1/venues`

Every ground, with city and match counts.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/venues`

```json
{
    "data": {
        "total": 1039,
        "data": [
            {
                "venue": "shere-bangla-national-stadium-dhaka-vvahpjzq2",
                "name": "Shere Bangla National Stadium, Mirpur",
                "city": "Dhaka",
                "matches": 360
            },
            {
                "venue": "edgbaston",
                "name": "Edgbaston, Birmingham",
                "city": "Birmingham",
                "matches": 308
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/venues

#### `GET /v1/venues/{venue}`

A ground: matches by format, highest totals and most runs there.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/venues/sophia-gardens`

```json
{
    "data": {
        "venue": "sophia-gardens",
        "name": "Sophia Gardens, Cardiff",
        "city": "Cardiff",
        "first_match": "2014-04-20",
        "latest_match": "2026-09-24",
        "matches_by_format": {
            "multi-day": 74,
            "odi": 7,
            "one-day": 35,
            "t20": 88,
            "t20i": 6
        },
        "highest_totals": [
            {
                "team": "Northamptonshire",
                "runs": 750,
                "wickets": 10,
                "overs": "227.3",
                "date": "2019-04-11",
                "format": "multi-day"
            },
            {
                "team": "Leicestershire",
                "runs": 586,
                "wickets": 7,
                "overs": "169",
                "date": "2026-04-24",
                "format": "multi-day"
            },
            "... 1 more"
        ],
        "most_runs": [
            {
                "player": "ks-carlson",
                "name": "KS Carlson",
                "runs": 4951
            },
            {
                "player": "ca-ingram",
                "name": "CA Ingram",
                "runs": 4539
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/venue

#### `GET /v1/venues/{venue}/matches`

Matches at a ground, with every filter of /v1/matches.

Plans: Free key (last 30 days), Match Week (last 30 days), Archive (to yesterday), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `date` | query | date | no | One day, YYYY-MM-DD |  |
| `from` | query | date | no | On or after |  |
| `to` | query | date | no | On or before |  |
| `year` | query | int | no | A calendar year |  |
| `month` | query | int | no | With year, 1 to 12 |  |
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |
| `gender` | query | text | no | male or female |  |
| `page` | query | int | no | Page number, from 1 |  |
| `limit` | query | int | no | Results per page, 1 to 100 (default 50) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/venues/sophia-gardens/matches`

```json
{
    "data": [
        {
            "match": "2026-09-24-glamorgan-v-essex",
            "date": "2026-09-24",
            "format": "multi-day",
            "gender": "male",
            "coverage": "full",
            "competition": "County Championship",
            "stage": "Match 69",
            "ground": null,
            "official_number": null,
            "teams": [
                {
                    "team": "glamorgan",
                    "name": "Glamorgan",
                    "score": "505",
                    "overs": "157.1",
                    "won": false
                },
                {
                    "team": "essex",
                    "name": "Essex",
                    "score": "129 & 351/6",
                    "overs": "85.3",
                    "won": false
                }
            ],
            "result": "Match drawn"
        },
        {
            "match": "2026-09-17-sri-lanka-v-england",
            "date": "2026-09-17",
            "format": "t20i",
            "gender": "male",
            "coverage": "full",
            "competition": "Sri Lanka tour of England",
            "stage": "Match 2",
            "ground": null,
            "official_number": null,
            "teams": [
                {
                    "team": "sri-lanka",
                    "name": "Sri Lanka",
                    "score": "145/9",
                    "overs": "20",
                    "won": false
                },
                {
                    "team": "england",
                    "name": "England",
                    "score": "146/4",
                    "overs": "12.1",
                    "won": true
                }
            ],
            "result": "England won by 6 wickets"
        },
        "... 1 more"
    ],
    "meta": {
        "plan": "plus",
        "count": 50,
        "next_cursor": "Y2RiOnAy",
        "page": 1,
        "per_page": 50,
        "total": 210,
        "total_pages": 5,
        "next_page": 2,
        "prev_page": null
    }
}
```

Page: https://cricketdatabase.com/documentation/venue-matches

### Competitions

#### `GET /v1/competitions`

Every competition, with kind, gender, span and match count.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/competitions`

```json
{
    "data": {
        "total": 1185,
        "data": [
            {
                "competition": "t20-blast",
                "name": "T20 Blast",
                "kind": "domestic",
                "gender": "male",
                "country": "England",
                "matches": 1570,
                "first_match": "2014-05-16",
                "latest_match": "2026-07-18"
            },
            {
                "competition": "county-championship",
                "name": "County Championship",
                "kind": "domestic",
                "gender": "male",
                "country": "England",
                "matches": 1483,
                "first_match": "2014-04-06",
                "latest_match": "2026-09-27"
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/competitions

#### `GET /v1/competitions/{competition}`

A competition: the names it was filed under, titles by team and all-time leaders.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/competitions/t20-blast`

```json
{
    "data": {
        "competition": "t20-blast",
        "name": "T20 Blast",
        "kind": "domestic",
        "gender": "male",
        "country": "England",
        "matches": 1570,
        "first_match": "2014-05-16",
        "latest_match": "2026-07-18",
        "also_filed_as": [
            "Vitality Blast",
            "NatWest T20 Blast",
            "... 1 more"
        ],
        "titles": {
            "Northamptonshire": 2,
            "Somerset": 2,
            "Nottinghamshire": 2,
            "Gloucestershire": 1,
            "Hampshire": 1,
            "Kent": 1,
            "Essex": 1,
            "Worcestershire": 1,
            "Lancashire": 1,
            "Warwickshire": 1
        },
        "most_runs": [
            {
                "player": "jm-vince",
                "name": "JM Vince",
                "runs": 5547,
                "innings": 166,
                "hundreds": 6
            },
            {
                "player": "dj-bell-drummond",
                "name": "DJ Bell-Drummond",
                "runs": 4702,
                "innings": 160,
                "hundreds": 3
            },
            "... 1 more"
        ],
        "most_wickets": [
            {
                "player": "dr-briggs",
                "name": "DR Briggs",
                "wickets": 206,
                "economy": 7.54
            },
            {
                "player": "cp-wood",
                "name": "CP Wood",
                "wickets": 182,
                "economy": 8.21
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/competition

#### `GET /v1/competitions/{competition}/seasons`

Every season with its champion, final and top run scorer and wicket taker.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/competitions/t20-blast/seasons`

```json
{
    "data": {
        "competition": "t20-blast",
        "seasons": [
            {
                "season": "2026",
                "slug": "2026",
                "matches": 115,
                "from": "2026-05-22",
                "to": "2026-07-18",
                "champion": "Northamptonshire",
                "final": {
                    "match": "2026-07-18-northamptonshire-v-hampshire",
                    "winner": "Northamptonshire",
                    "loser": "Hampshire",
                    "margin": "14 runs"
                },
                "most_runs": {
                    "player": "jj-weatherley",
                    "name": "JJ Weatherley",
                    "runs": 591
                },
                "most_wickets": {
                    "player": "hasan-ali",
                    "name": "Hasan Ali",
                    "wickets": 27
                }
            },
            {
                "season": "2025",
                "slug": "2025",
                "matches": 132,
                "from": "2025-05-29",
                "to": "2025-09-13",
                "champion": "Somerset",
                "final": {
                    "match": "2025-09-13-hampshire-v-somerset",
                    "winner": "Somerset",
                    "loser": "Hampshire",
                    "margin": "6 wickets"
                },
                "most_runs": {
                    "player": "te-albert",
                    "name": "TE Albert",
                    "runs": 633
                },
                "most_wickets": {
                    "player": "rp-meredith",
                    "name": "RP Meredith",
                    "wickets": 28
                }
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/seasons

#### `GET /v1/competitions/{competition}/seasons/{season}`

A season: every result, the results table and the leaders. Seasons like 2025/26 are written 2025-26.

Plans: Free key (in full), Match Week (in full), Archive (in full), Pro (in full), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/competitions/t20-blast/seasons/2025`

```json
{
    "data": {
        "competition": "t20-blast",
        "season": "2025",
        "matches": 132,
        "champion": "Somerset",
        "table": [
            {
                "team": "somerset",
                "name": "Somerset",
                "played": 17,
                "won": 14,
                "lost": 3,
                "no_result": 0
            },
            {
                "team": "surrey",
                "name": "Surrey",
                "played": 15,
                "won": 11,
                "lost": 4,
                "no_result": 0
            },
            "... 1 more"
        ],
        "most_runs": [
            {
                "player": "te-albert",
                "name": "TE Albert",
                "runs": 633,
                "innings": 17,
                "high_score": 98
            },
            {
                "player": "wcf-smeed",
                "name": "WCF Smeed",
                "runs": 620,
                "innings": 17,
                "high_score": 94
            },
            "... 1 more"
        ],
        "most_wickets": [
            {
                "player": "rp-meredith",
                "name": "RP Meredith",
                "wickets": 28,
                "economy": 8.62
            },
            {
                "player": "sw-currie",
                "name": "SW Currie",
                "wickets": 27,
                "economy": 8.65
            },
            "... 1 more"
        ],
        "results": [
            {
                "match": "2025-09-13-hampshire-v-somerset",
                "date": "2025-09-13",
                "teams": [
                    {
                        "name": "Hampshire",
                        "score": "194/6",
                        "won": false
                    },
                    {
                        "name": "Somerset",
                        "score": "195/4",
                        "won": true
                    }
                ],
                "result": "Somerset won by 6 wickets",
                "stage": "Final"
            },
            {
                "match": "2025-09-13-northamptonshire-v-hampshire",
                "date": "2025-09-13",
                "teams": [
                    {
                        "name": "Northamptonshire",
                        "score": "158/7",
                        "won": false
                    },
                    {
                        "name": "Hampshire",
                        "score": "155/4",
                        "won": true
                    }
                ],
                "result": "Hampshire won by 6 wickets (DLS)",
                "stage": "Semi Final"
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/season

### Records

#### `GET /v1/records`

Record lists. Lower plans get the top 10; Archive and Analyst Pro the top 100.

Plans: Free key (sample), Match Week (sample), Archive (in full), Pro (in full), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `type` | query | text | no | most-runs, most-wickets, highest-scores, best-bowling or team-totals | `most-runs` |
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day (default test) | `test` |
| `gender` | query | text | no | male or female (default male) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/records?type=most-runs&format=test`

```json
{
    "data": {
        "type": "most-runs",
        "format": "test",
        "gender": "male",
        "data": [
            {
                "player": "je-root",
                "name": "JE Root",
                "runs": 14278,
                "innings": 309,
                "outs": 283,
                "balls": 24783,
                "hundreds": 41
            },
            {
                "player": "an-cook",
                "name": "AN Cook",
                "runs": 12472,
                "innings": 291,
                "outs": 275,
                "balls": 26562,
                "hundreds": 33
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/records

### Analytics

#### `GET /v1/analytics/matchups`

Batter against bowler: balls, runs, dismissals, strike rate and average. Analyst Pro adds dots, boundaries, how out and every format separately.

Plans: Free key (sample), Match Week (sample), Archive (sample), Pro (sample), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `batter` | query | player address | yes |  | `je-root` |
| `bowler` | query | player address | yes |  | `pj-cummins` |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/matchups?batter=je-root&bowler=pj-cummins`

```json
{
    "data": {
        "batter": {
            "player": "je-root",
            "name": "JE Root"
        },
        "bowler": {
            "player": "pj-cummins",
            "name": "PJ Cummins"
        },
        "balls": 643,
        "runs": 348,
        "dismissals": 16,
        "strike_rate": 54.12,
        "average": 21.75,
        "dots": 461,
        "fours": 40,
        "sixes": 1,
        "matches": 28,
        "by_format": {
            "odi": {
                "balls": 84,
                "runs": 54,
                "dismissals": 3,
                "dots": 50,
                "fours": 5,
                "sixes": 0,
                "matches": 8,
                "how_out": {
                    "caught": 3
                },
                "strike_rate": 64.29,
                "average": 18
            },
            "test": {
                "balls": 559,
                "runs": 294,
                "dismissals": 13,
                "dots": 411,
                "fours": 35,
                "sixes": 1,
                "matches": 20,
                "how_out": {
                    "bowled": 2,
                    "caught": 9,
                    "lbw": 2
                },
                "strike_rate": 52.59,
                "average": 22.62
            }
        }
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/matchups

#### `GET /v1/analytics/players/{player}/splits` (Analyst Pro)

Batting by opposition, venue, year, innings and position; bowling by opposition, venue, year and innings.

Plans: Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/players/je-root/splits`

```json
{
    "data": {
        "player": "je-root",
        "format": "all",
        "batting": {
            "by_opposition": [
                {
                    "split": "Australia",
                    "innings": 111,
                    "runs": 3750,
                    "outs": 99,
                    "average": 37.88,
                    "strike_rate": 56.39,
                    "hundreds": 6,
                    "fifties": 25
                },
                {
                    "split": "India",
                    "innings": 96,
                    "runs": 4644,
                    "outs": 82,
                    "average": 56.63,
                    "strike_rate": 61.51,
                    "hundreds": 16,
                    "fifties": 19
                },
                "... 1 more"
            ],
            "by_venue": [
                {
                    "split": "Headingley, Leeds",
                    "innings": 39,
                    "runs": 1903,
                    "outs": 33,
                    "average": 57.67,
                    "strike_rate": 74.22,
                    "hundreds": 5,
                    "fifties": 8
                },
                {
                    "split": "Lord's",
                    "innings": 34,
                    "runs": 1554,
                    "outs": 32,
                    "average": 48.56,
                    "strike_rate": 60.94,
                    "hundreds": 4,
                    "fifties": 7
                },
                "... 1 more"
            ],
            "by_year": [
                {
                    "split": "2018",
                    "innings": 63,
                    "runs": 2166,
                    "outs": 53,
                    "average": 40.87,
                    "strike_rate": 66.69,
                    "hundreds": 5,
                    "fifties": 12
                },
                {
                    "split": "2016",
                    "innings": 62,
                    "runs": 2959,
                    "outs": 56,
                    "average": 52.84,
                    "strike_rate": 75.81,
                    "hundreds": 6,
                    "fifties": 19
                },
                "... 1 more"
            ],
            "by_innings": [
                {
                    "split": 1,
                    "innings": 254,
                    "runs": 10618,
                    "outs": 239,
                    "average": 44.43,
                    "strike_rate": 74.74,
                    "hundreds": 28,
                    "fifties": 55
                },
                {
                    "split": 2,
                    "innings": 245,
                    "runs": 10780,
                    "outs": 198,
                    "average": 54.44,
                    "strike_rate": 73.91,
                    "hundreds": 25,
                    "fifties": 56
                },
                "... 1 more"
            ],
            "by_position": [
                {
                    "split": 4,
                    "innings": 314,
                    "runs": 13616,
                    "outs": 285,
                    "average": 47.78,
                    "strike_rate": 64.88,
                    "hundreds": 39,
                    "fifties": 62
                },
                {
                    "split": 3,
                    "innings": 242,
                    "runs": 9758,
                    "outs": 211,
                    "average": 46.25,
                    "strike_rate": 79.36,
                    "hundreds": 19,
                    "fifties": 63
                },
                "... 1 more"
            ]
        },
        "bowling": {
            "by_opposition": [
                {
                    "split": "Australia",
                    "matches": 52,
                    "wickets": 34,
                    "runs": 1461,
                    "average": 42.97,
                    "economy": 4.34
                },
                {
                    "split": "India",
                    "matches": 39,
                    "wickets": 22,
                    "runs": 1256,
                    "average": 57.09,
                    "economy": 3.82
                },
                "... 1 more"
            ],
            "by_venue": [
                {
                    "split": "Headingley, Leeds",
                    "matches": 21,
                    "wickets": 20,
                    "runs": 657,
                    "average": 32.85,
                    "economy": 4.16
                },
                {
                    "split": "Trent Bridge, Nottingham",
                    "matches": 14,
                    "wickets": 7,
                    "runs": 248,
                    "average": 35.43,
                    "economy": 4.31
                },
                "... 1 more"
            ],
            "by_year": [
                {
                    "split": "2013",
                    "matches": 27,
                    "wickets": 8,
                    "runs": 559,
                    "average": 69.88,
                    "economy": 4.74
                },
                {
                    "split": "2014",
                    "matches": 26,
                    "wickets": 12,
                    "runs": 486,
                    "average": 40.5,
                    "economy": 4.54
                },
                "... 1 more"
            ],
            "by_innings": [
                {
                    "split": 1,
                    "matches": 116,
                    "wickets": 53,
                    "runs": 2494,
                    "average": 47.06,
                    "economy": 5.03
                },
                {
                    "split": 2,
                    "matches": 107,
                    "wickets": 54,
                    "runs": 2236,
                    "average": 41.41,
                    "economy": 4.26
                },
                "... 1 more"
            ]
        }
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/splits

#### `GET /v1/analytics/players/{player}/phases` (Analyst Pro)

Powerplay, middle and death: strike rate, dot and boundary rates and dismissals; bowling economy and wickets.

Plans: Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | t20i, t20, odi or one-day (default t20) | `t20i` |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/players/je-root/phases?format=t20i`

```json
{
    "data": {
        "player": "je-root",
        "format": "t20i",
        "phases": [
            {
                "phase": "powerplay",
                "overs": "1-6"
            },
            {
                "phase": "middle",
                "overs": "7-15"
            },
            "... 1 more"
        ],
        "batting": [
            {
                "phase": "powerplay",
                "balls": 209,
                "runs": 259,
                "strike_rate": 123.92,
                "dot_pct": 44,
                "boundary_pct": 18.7,
                "dismissals": 2
            },
            {
                "phase": "middle",
                "balls": 416,
                "runs": 502,
                "strike_rate": 120.67,
                "dot_pct": 28.4,
                "boundary_pct": 12,
                "dismissals": 15
            },
            "... 1 more"
        ],
        "bowling": [
            {
                "phase": "powerplay",
                "balls": 24,
                "runs": 32,
                "wickets": 2,
                "economy": 8,
                "dot_pct": 54.2
            },
            {
                "phase": "middle",
                "balls": 60,
                "runs": 107,
                "wickets": 4,
                "economy": 10.7,
                "dot_pct": 25
            }
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/phases

#### `GET /v1/analytics/players/{player}/dismissals` (Analyst Pro)

How a player gets out: by kind, by bowler and by balls faced.

Plans: Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/players/je-root/dismissals`

```json
{
    "data": {
        "player": "je-root",
        "format": "all",
        "dismissals": 576,
        "by_how_out": [
            {
                "how_out": "caught",
                "count": 329,
                "pct": 57.1
            },
            {
                "how_out": "lbw",
                "count": 102,
                "pct": 17.7
            },
            "... 1 more"
        ],
        "by_bowler": [
            {
                "player": "pj-cummins",
                "name": "PJ Cummins",
                "count": 16
            },
            {
                "player": "jj-bumrah",
                "name": "JJ Bumrah",
                "count": 15
            },
            "... 1 more"
        ],
        "by_balls_faced": [
            {
                "balls": "0-9",
                "count": 94
            },
            {
                "balls": "10-19",
                "count": 97
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/dismissals

#### `GET /v1/analytics/players/{player}/scoring` (Analyst Pro)

Scoring shape: the share of dots, singles, twos, threes, fours and sixes, boundary runs and sixes per 100 balls.

Plans: Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/players/je-root/scoring`

```json
{
    "data": {
        "player": "je-root",
        "format": "all",
        "balls": 39829,
        "runs": 27706,
        "strike_rate": 69.56,
        "pct": {
            "dots": 60,
            "singles": 26.8,
            "twos": 5,
            "threes": 0.9,
            "fours": 6.9,
            "sixes": 0.4
        },
        "counts": {
            "dots": 23913,
            "singles": 10660,
            "twos": 1982,
            "threes": 350,
            "fours": 2745,
            "sixes": 167,
            "all_run_boundaries": 10
        },
        "boundary_runs_pct": 43.2,
        "sixes_per_100_balls": 0.4
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/scoring

#### `GET /v1/analytics/players/{player}/form`

Rolling average and strike rate over recent innings. Lower plans get the last five.

Plans: Free key (sample), Match Week (sample), Archive (sample), Pro (sample), Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | test, odi, t20i, t20, multi-day, one-day |  |
| `innings` | query | int | no | 5 to 100 (default 20) |  |
| `window` | query | int | no | 2 to 20 (default 5) |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/players/je-root/form`

```json
{
    "data": {
        "player": "je-root",
        "format": "all",
        "innings": [
            {
                "match": "2026-07-10-lancashire-v-yorkshire",
                "date": "2026-07-10",
                "format": "t20",
                "runs": 4,
                "balls": 5,
                "out": true,
                "rolling_average": 33.2,
                "rolling_strike_rate": 61.48
            },
            {
                "match": "2026-07-12-yorkshire-v-nottinghamshire",
                "date": "2026-07-12",
                "format": "t20",
                "runs": 2,
                "balls": 4,
                "out": true,
                "rolling_average": 24.4,
                "rolling_strike_rate": 56.22
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus",
        "window": 5
    }
}
```

Page: https://cricketdatabase.com/documentation/form

#### `GET /v1/analytics/venues/{venue}/par-scores` (Analyst Pro)

First-innings totals by format and year: average, median, highest, lowest, and batting first against chasing.

Plans: Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/venues/sophia-gardens/par-scores`

```json
{
    "data": {
        "venue": "sophia-gardens",
        "name": "Sophia Gardens, Cardiff",
        "by_format": {
            "multi-day": {
                "matches": 74,
                "average_first_innings": 291.1,
                "median_first_innings": 280,
                "highest": 570,
                "lowest": 69,
                "batting_first_won_pct": 36.6,
                "chasing_won_pct": 63.4,
                "by_year": [
                    {
                        "year": 2014,
                        "matches": 6,
                        "average_first_innings": 231,
                        "median_first_innings": 246.5,
                        "highest": 357,
                        "lowest": 109,
                        "batting_first_won_pct": 66.7,
                        "chasing_won_pct": 33.3
                    },
                    {
                        "year": 2015,
                        "matches": 6,
                        "average_first_innings": 340,
                        "median_first_innings": 311.5,
                        "highest": 563,
                        "lowest": 205,
                        "batting_first_won_pct": 100,
                        "chasing_won_pct": 0
                    },
                    "... 1 more"
                ]
            },
            "one-day": {
                "matches": 33,
                "average_first_innings": 250.3,
                "median_first_innings": 264,
                "highest": 340,
                "lowest": 73,
                "batting_first_won_pct": 48.5,
                "chasing_won_pct": 51.5,
                "by_year": [
                    {
                        "year": 2014,
                        "matches": 3,
                        "average_first_innings": 195.3,
                        "median_first_innings": 185,
                        "highest": 227,
                        "lowest": 174,
                        "batting_first_won_pct": 33.3,
                        "chasing_won_pct": 66.7
                    },
                    {
                        "year": 2015,
                        "matches": 2,
                        "average_first_innings": 302.5,
                        "median_first_innings": 302.5,
                        "highest": 317,
                        "lowest": 288,
                        "batting_first_won_pct": 50,
                        "chasing_won_pct": 50
                    },
                    "... 1 more"
                ]
            },
            "odi": {
                "matches": 7,
                "average_first_innings": 211.4,
                "median_first_innings": 201,
                "highest": 308,
                "lowest": 125,
                "batting_first_won_pct": 14.3,
                "chasing_won_pct": 85.7,
                "by_year": [
                    {
                        "year": 2019,
                        "matches": 2,
                        "average_first_innings": 163,
                        "median_first_innings": 163,
                        "highest": 201,
                        "lowest": 125,
                        "batting_first_won_pct": 50,
                        "chasing_won_pct": 50
                    },
                    {
                        "year": 2021,
                        "matches": 1,
                        "average_first_innings": 141,
                        "median_first_innings": 141,
                        "highest": 141,
                        "lowest": 141,
                        "batting_first_won_pct": 0,
                        "chasing_won_pct": 100
                    },
                    "... 1 more"
                ]
            },
            "t20": {
                "matches": 86,
                "average_first_innings": 147.8,
                "median_first_innings": 149,
                "highest": 243,
                "lowest": 73,
                "batting_first_won_pct": 53.5,
                "chasing_won_pct": 46.5,
                "by_year": [
                    {
                        "year": 2021,
                        "matches": 16,
                        "average_first_innings": 144.1,
                        "median_first_innings": 150,
                        "highest": 201,
                        "lowest": 95,
                        "batting_first_won_pct": 43.8,
                        "chasing_won_pct": 56.3
                    },
                    {
                        "year": 2022,
                        "matches": 14,
                        "average_first_innings": 135.2,
                        "median_first_innings": 132,
                        "highest": 171,
                        "lowest": 75,
                        "batting_first_won_pct": 57.1,
                        "chasing_won_pct": 42.9
                    },
                    "... 1 more"
                ]
            },
            "t20i": {
                "matches": 6,
                "average_first_innings": 147,
                "median_first_innings": 137,
                "highest": 207,
                "lowest": 97,
                "batting_first_won_pct": 33.3,
                "chasing_won_pct": 66.7,
                "by_year": [
                    {
                        "year": 2021,
                        "matches": 2,
                        "average_first_innings": 120,
                        "median_first_innings": 120,
                        "highest": 129,
                        "lowest": 111,
                        "batting_first_won_pct": 0,
                        "chasing_won_pct": 100
                    },
                    {
                        "year": 2022,
                        "matches": 1,
                        "average_first_innings": 207,
                        "median_first_innings": 207,
                        "highest": 207,
                        "lowest": 207,
                        "batting_first_won_pct": 100,
                        "chasing_won_pct": 0
                    },
                    "... 1 more"
                ]
            }
        }
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/par-scores

#### `GET /v1/analytics/venues/{venue}/toss` (Analyst Pro)

How often the toss winner bats, and how often they win after batting or fielding.

Plans: Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/venues/sophia-gardens/toss`

```json
{
    "data": {
        "venue": "sophia-gardens",
        "name": "Sophia Gardens, Cardiff",
        "by_format": {
            "multi-day": {
                "matches": 74,
                "chose_bat_pct": 31.1,
                "toss_winner_won_pct": 65.9,
                "won_when_chose_bat_pct": 53.8,
                "won_when_chose_field_pct": 71.4
            },
            "one-day": {
                "matches": 35,
                "chose_bat_pct": 40,
                "toss_winner_won_pct": 45.5,
                "won_when_chose_bat_pct": 41.7,
                "won_when_chose_field_pct": 47.6
            },
            "odi": {
                "matches": 7,
                "chose_bat_pct": 0,
                "toss_winner_won_pct": 85.7,
                "won_when_chose_bat_pct": null,
                "won_when_chose_field_pct": 85.7
            },
            "t20i": {
                "matches": 6,
                "chose_bat_pct": 33.3,
                "toss_winner_won_pct": 33.3,
                "won_when_chose_bat_pct": 0,
                "won_when_chose_field_pct": 50
            },
            "t20": {
                "matches": 88,
                "chose_bat_pct": 29.5,
                "toss_winner_won_pct": 60.5,
                "won_when_chose_bat_pct": 73.1,
                "won_when_chose_field_pct": 55
            }
        }
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/toss

#### `GET /v1/analytics/teams/{team}/phases` (Analyst Pro)

A team's run rate and wickets by phase, batting and bowling, year by year.

Plans: Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | t20i, t20, odi or one-day (default t20) | `t20i` |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/teams/england/phases?format=t20i`

```json
{
    "data": {
        "team": "england",
        "format": "t20i",
        "by_year": [
            {
                "year": "2026",
                "bowling": {
                    "death": {
                        "balls": 848,
                        "runs": 1193,
                        "wickets": 92,
                        "run_rate": 8.44
                    },
                    "middle": {
                        "balls": 1708,
                        "runs": 2160,
                        "wickets": 90,
                        "run_rate": 7.59
                    },
                    "powerplay": {
                        "balls": 1152,
                        "runs": 1581,
                        "wickets": 67,
                        "run_rate": 8.23
                    }
                },
                "batting": {
                    "death": {
                        "balls": 674,
                        "runs": 1221,
                        "wickets": 52,
                        "run_rate": 10.87
                    },
                    "middle": {
                        "balls": 1611,
                        "runs": 2439,
                        "wickets": 51,
                        "run_rate": 9.08
                    },
                    "powerplay": {
                        "balls": 1116,
                        "runs": 1612,
                        "wickets": 58,
                        "run_rate": 8.67
                    }
                }
            },
            {
                "year": "2025",
                "bowling": {
                    "death": {
                        "balls": 603,
                        "runs": 986,
                        "wickets": 55,
                        "run_rate": 9.81
                    },
                    "middle": {
                        "balls": 1240,
                        "runs": 1723,
                        "wickets": 67,
                        "run_rate": 8.34
                    },
                    "powerplay": {
                        "balls": 886,
                        "runs": 1301,
                        "wickets": 42,
                        "run_rate": 8.81
                    }
                },
                "batting": {
                    "death": {
                        "balls": 523,
                        "runs": 842,
                        "wickets": 46,
                        "run_rate": 9.66
                    },
                    "middle": {
                        "balls": 1234,
                        "runs": 1719,
                        "wickets": 72,
                        "run_rate": 8.36
                    },
                    "powerplay": {
                        "balls": 894,
                        "runs": 1414,
                        "wickets": 42,
                        "run_rate": 9.49
                    }
                }
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/team-phases

#### `GET /v1/analytics/competitions/{competition}/trends` (Analyst Pro)

Season by season: first-innings average, run rate, runs per wicket, boundaries per match and chase wins.

Plans: Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/competitions/t20-blast/trends`

```json
{
    "data": {
        "competition": "t20-blast",
        "seasons": [
            {
                "season": "2026",
                "matches": 115,
                "average_first_innings": 177.2,
                "run_rate": 8.9,
                "runs_per_wicket": 24.79,
                "fours_per_match": 29.5,
                "sixes_per_match": 13.2,
                "chasing_won_pct": 49.6
            },
            {
                "season": "2025",
                "matches": 132,
                "average_first_innings": 179.9,
                "run_rate": 8.98,
                "runs_per_wicket": 24.97,
                "fours_per_match": 29.5,
                "sixes_per_match": 13.5,
                "chasing_won_pct": 47.3
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/trends

#### `GET /v1/analytics/chases` (Analyst Pro)

Chase success by target band. Rain-affected chases are left out.

Plans: Analyst Pro (in full)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `format` | query | text | no | t20i, t20, odi or one-day (default t20i) | `t20i` |
| `gender` | query | text | no | male or female |  |
| `competition` | query | competition address | no |  |  |
| `venue` | query | venue address | no |  |  |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/analytics/chases?format=t20i`

```json
{
    "data": {
        "format": "t20i",
        "gender": "male",
        "chases": 3697,
        "bands": [
            {
                "target": "60-79",
                "chases": 119,
                "won": 116,
                "won_pct": 97.5
            },
            {
                "target": "80-99",
                "chases": 240,
                "won": 221,
                "won_pct": 92.1
            },
            "... 1 more"
        ]
    },
    "meta": {
        "plan": "plus",
        "note": "Targets set in the first innings; rain-affected (DLS) chases left out, and targets under 60, which are matches cut short."
    }
}
```

Page: https://cricketdatabase.com/documentation/chases

#### `GET /v1/analytics/matches/{match}/worm`

Runs and wickets per over and the running totals for every innings, for worm and Manhattan charts.

Plans: Free key (sample), Match Week (sample), Archive (sample), Pro (sample), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/analytics/matches/2026-09-17-sri-lanka-v-england/worm`

```json
{
    "data": {
        "match": "2026-09-17-sri-lanka-v-england",
        "result": "England won by 6 wickets",
        "innings": [
            {
                "innings": 1,
                "team": "sri-lanka",
                "name": "Sri Lanka",
                "total": 145,
                "overs": [
                    {
                        "over": 1,
                        "runs": 3,
                        "wickets": 0,
                        "total": 3,
                        "total_wickets": 0
                    },
                    {
                        "over": 2,
                        "runs": 14,
                        "wickets": 0,
                        "total": 17,
                        "total_wickets": 0
                    },
                    "... 1 more"
                ]
            },
            {
                "innings": 2,
                "team": "england",
                "name": "England",
                "total": 146,
                "overs": [
                    {
                        "over": 1,
                        "runs": 4,
                        "wickets": 0,
                        "total": 4,
                        "total_wickets": 0
                    },
                    {
                        "over": 2,
                        "runs": 16,
                        "wickets": 0,
                        "total": 20,
                        "total_wickets": 0
                    },
                    "... 1 more"
                ]
            }
        ]
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/worm

#### `GET /v1/analytics/matches/{match}/win-probability`

After each over of a one-day or T20 match, how likely the batting side was to win, from models fitted on our own ball-by-ball record of completed matches: one for the first innings, one for the chase. model gives when they were fitted, how many matches they learned from, and their Brier score on matches held back from fitting (0 is perfect, 0.25 is a coin toss).

Plans: Free key (sample), Match Week (sample), Archive (sample), Pro (sample), Analyst Pro (in full)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded, no_ball_by_ball, no_scorecard

Example: `GET https://api.cricketdatabase.com/v1/analytics/matches/2026-09-17-sri-lanka-v-england/win-probability`

```json
{
    "error": {
        "code": "server_error",
        "message": "The win-probability model is being fitted for the first time. Try again later.",
        "docs": "https://cricketdatabase.com/documentation/guides/errors"
    }
}
```

Page: https://cricketdatabase.com/documentation/win-probability

### Bulk files

#### `GET /v1/export`

Every match held ball by ball as files to download instead of pages to call: matches, innings, batting, bowling and every ball, one file a year for each, and one file each for players, teams and grounds, as gzipped CSV or gzipped JSON lines. Each entry gives its rows, size, sha256 and download address. Files are rebuilt each night up to yesterday, a year only when its matches changed. Addresses in the files are the same as everywhere in the API.

Plans: Archive (to yesterday), Pro (to yesterday), Analyst Pro (to yesterday)

| Parameter | In | Type | Required | Description | Example |
|---|---|---|---|---|---|
| `table` | query | text | no | matches, innings, batting, bowling, deliveries, players, teams or grounds | `matches` |
| `year` | query | text | no | Four digits, such as 2019 |  |
| `format` | query | text | no | csv or jsonl | `csv` |

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/export?table=matches&format=csv`

```json
{
    "data": {
        "files": [
            {
                "file": "matches-2001-csv",
                "table": "matches",
                "year": 2001,
                "format": "csv",
                "filename": "matches-2001.csv.gz",
                "rows": 1,
                "bytes": 472,
                "sha256": "1d536e7d42dd0c0c6a0dbf440ec9a10b3b3acfeb84a2c366b89dc2051e1d9767",
                "built_at": "2026-10-10T06:57:31Z",
                "download": "https://api.cricketdatabase.com/v1/export/matches-2001-csv"
            },
            {
                "file": "matches-2002-csv",
                "table": "matches",
                "year": 2002,
                "format": "csv",
                "filename": "matches-2002.csv.gz",
                "rows": 5,
                "bytes": 1008,
                "sha256": "7990d9d87aed9d83ca7aa09fde914c8a2b1b4beda4822184cbafbfa1b803af54",
                "built_at": "2026-10-10T06:57:31Z",
                "download": "https://api.cricketdatabase.com/v1/export/matches-2002-csv"
            },
            "... 1 more"
        ],
        "count": 26,
        "built_at": "2026-10-10T07:04:46Z",
        "up_to": "2026-10-09",
        "years": {
            "from": 2001,
            "to": 2026
        },
        "tables": [
            "matches",
            "innings",
            "... 1 more"
        ],
        "formats": [
            "csv",
            "jsonl"
        ]
    },
    "meta": {
        "plan": "plus",
        "note": "One file a year for matches, innings, batting, bowling and deliveries; one file each for players, teams and grounds. Each download counts as one call. Files are rebuilt each night, a year only when its matches changed."
    }
}
```

Page: https://cricketdatabase.com/documentation/export

#### `GET /v1/export/{file}`

One bulk file, sent as it is: gzipped CSV (a header row, then one row a record) or gzipped JSON lines (one object a line), with Content-Length, an ETag of its sha256 and X-Rows. Each download counts as one call. The example shows the file's entry; the call itself answers the file.

Plans: Archive (to yesterday), Pro (to yesterday), Analyst Pro (to yesterday)

Errors: unauthorized, unknown_parameter, bad_request, upgrade_required, not_found, rate_limited, quota_exceeded

Example: `GET https://api.cricketdatabase.com/v1/export/players-csv`

```json
{
    "data": {
        "file": "players-csv",
        "table": "players",
        "year": null,
        "format": "csv",
        "filename": "players.csv.gz",
        "rows": 13967,
        "bytes": 382770,
        "sha256": "d7e3bfec99e4fbff95dccac9ed8c6478011202a1eadbe70447484b43ca30c5e4",
        "built_at": "2026-10-10T07:04:46Z",
        "download": "https://api.cricketdatabase.com/v1/export/players-csv"
    },
    "meta": {
        "plan": "plus"
    }
}
```

Page: https://cricketdatabase.com/documentation/export-file

## MCP tools

The MCP server at https://cricketdatabase.com/mcp offers these tools; each makes one call to the API with the caller's own key, on the caller's plan.

#### find

Find players, teams, venues and competitions by name, including the other names a player has been recorded under. Returns the address each of the other tools takes. Use it first whenever you have a name.

Calls: https://cricketdatabase.com/documentation/search
- `q` (string, required): A name, at least 2 characters.

#### search_matches

Matches, newest first, filtered by date, team, venue, competition, format, gender or coverage. Ball by ball runs from December 2001; every men's Test, ODI and T20 international back to 1877 is listed with its scorecard (coverage scorecard), its innings totals (coverage totals) or its result (coverage result_only). The free key sees the last 30 days.

Calls: https://cricketdatabase.com/documentation/matches
- `date` (string): One day, YYYY-MM-DD.
- `from` (string): On or after this day, YYYY-MM-DD.
- `to` (string): On or before this day, YYYY-MM-DD.
- `year` (integer): A calendar year.
- `month` (integer): With year, 1 to 12.
- `format` (string): Format: test, odi, t20i, t20, multi-day or one-day.
- `gender` (string): male or female.
- `team` (string): A team address from find.
- `venue` (string): A venue address from find.
- `competition` (string): A competition address from find.
- `coverage` (string): full (ball by ball, with its scorecard), scorecard (each batter's and bowler's line, no balls), totals (innings totals, extras and fall of wickets) or result_only (the result only).
- `limit` (integer): How many, 1 to 100 (default 50).

#### latest_results

Every result from the latest day in the database.

Calls: https://cricketdatabase.com/documentation/results-yesterday

#### live_scores

Matches in play now, men and women, international and domestic, with the score and the state of play, updated every minute. state=upcoming lists the next 24 hours, finished the last 48. Match Week, Pro and Analyst Pro.

Calls: https://cricketdatabase.com/documentation/live
- `state` (string): live (default), upcoming, finished or all.
- `international` (string): true for Tests, ODIs and T20 internationals only.

#### live_match

One live match: batting and bowling so far, who is in and on strike, the bowler, the partnership, the chase and the last 12 balls. Match Week, Pro and Analyst Pro.

Calls: https://cricketdatabase.com/documentation/live-match
- `match` (string, required): The live match address, like 2026-10-03-india-v-west-indies. live_scores gives it.

#### get_match

One match: teams, result, toss, venue, officials, player of the match and the innings totals; for an international without a scorecard, its innings totals, extras and fall of wickets when held.

Calls: https://cricketdatabase.com/documentation/match
- `match` (string, required): The match address, like 2026-09-17-sri-lanka-v-england. search_matches and latest_results give it.

#### get_scorecard

The full scorecard: batting with dismissals, bowling, extras, did not bat and fall of wickets, and the weather at the ground on each day. Older internationals held without their balls (coverage scorecard) answer each batter's and bowler's line, with balls_per_over.

Calls: https://cricketdatabase.com/documentation/scorecard
- `match` (string, required): The match address, like 2026-09-17-sri-lanka-v-england. search_matches and latest_results give it.

#### get_deliveries

Every ball of a match: batter, non-striker, bowler, runs, extras and wickets. The free key gets the first over.

Calls: https://cricketdatabase.com/documentation/deliveries
- `match` (string, required): The match address, like 2026-09-17-sri-lanka-v-england. search_matches and latest_results give it.

#### get_partnerships

Every partnership in a match: the pair, runs, balls and how it ended.

Calls: https://cricketdatabase.com/documentation/partnerships
- `match` (string, required): The match address, like 2026-09-17-sri-lanka-v-england. search_matches and latest_results give it.

#### player_career

Career batting and bowling for a player, format by format.

Calls: https://cricketdatabase.com/documentation/player-stats
- `player` (string, required): The player address, like je-root. find gives it.

#### player_innings

Every batting innings of a player, newest first. Lower plans get the last ten.

Calls: https://cricketdatabase.com/documentation/player-innings
- `player` (string, required): The player address, like je-root. find gives it.
- `format` (string): Format: test, odi, t20i, t20, multi-day or one-day.
- `year` (integer): A calendar year.
- `limit` (integer): How many, 1 to 100 (default 50).

#### head_to_head

Two teams against each other, by format, with the last ten meetings.

Calls: https://cricketdatabase.com/documentation/head-to-head
- `team` (string, required): A team address from find, like england.
- `other` (string, required): The other team address, like australia.

#### competition

A competition: the names it was filed under, titles by team and its all-time leaders.

Calls: https://cricketdatabase.com/documentation/competition
- `competition` (string, required): A competition address from find.

#### top_performances

Record lists: most runs, most wickets, highest scores, best bowling or team totals. Lower plans get the top 10.

Calls: https://cricketdatabase.com/documentation/records
- `type` (string, required): Which list.
- `format` (string): Format (default test).
- `gender` (string): male or female (default male).

#### batter_vs_bowler

One batter against one bowler: balls, runs, dismissals, strike rate and average. Analyst Pro adds dots, boundaries, how out and each format.

Calls: https://cricketdatabase.com/documentation/matchups
- `batter` (string, required): The batter address from find.
- `bowler` (string, required): The bowler address from find.

#### player_splits

A player by opposition, venue, year, innings and batting position; bowling by opposition, venue, year and innings.

Calls: https://cricketdatabase.com/documentation/splits
- `player` (string, required): The player address, like je-root. find gives it.
- `format` (string): Format: test, odi, t20i, t20, multi-day or one-day.

## Guides

### Getting started

Your first call in a minute: the base address, your key and the shape of a response.

Address: https://cricketdatabase.com/documentation/guides/getting-started

The API answers `GET` requests under `https://api.cricketdatabase.com/v1` with JSON. You need one thing to start: a key, which the free plan gives you with no card.

#### Your first call

0
That returns every result from the latest day in the database: each match's address, date, format, the two teams with their scores, and the result.

#### What a response looks like

Every answer has the same two parts: `data`, the thing you asked for, and `meta`, about the answer: your plan, and for lists the count and the way to the next page.

1
Everything that refers to something else carries its address, such as `{"player": "je-root", "name": "JE Root"}`, so you can follow it with another call. The version in the address is optional: `/matches` is `/v1/matches`.

#### Finding your way

`/v1` on its own lists every endpoint, and `/v1/status` answers without a key, so it suits a health check. `/v1/search?q=` finds players, teams, grounds and competitions by name when you do not know the address.

Next, read [What each plan can call](https://cricketdatabase.com/documentation/guides/plans), so that nothing you build depends on data your plan does not include.

### Authentication

Send your key as a bearer token or as X-API-Key, and keep it off the browser.

Address: https://cricketdatabase.com/documentation/guides/authentication

Every call except `/v1/status` and `/v1` needs a key. Keys start `cdb_live_` and have 32 more characters.

#### Sending it

Send it as a bearer token:

0
or, where a tool makes that awkward, as its own header:

1
Both work on every endpoint. The key is never accepted in the address, because addresses end up in logs, browser history and anything a link is pasted into: a `?key=` gets `400 bad_request`.

#### Keeping it safe

We store only a hash of your key and its first 12 characters, so we cannot show it to you again: keep a copy when it is made. Call the API from your server rather than from a web page, where anyone could read the key from the page. If a key has leaked, revoke it; calls with a revoked key stop at once.

#### When it goes wrong

No key, a key we do not recognise and a revoked key all give `401 unauthorized`, with a message saying which. See [Errors](https://cricketdatabase.com/documentation/guides/errors) for the rest.

### What each plan can call

Every endpoint on every plan: in full, in a window, to yesterday, as a sample, or not at all.

Address: https://cricketdatabase.com/documentation/guides/plans

See Plans above.

### Addresses

How matches, players, teams, venues and competitions are addressed, and what happens when two share a name.

Address: https://cricketdatabase.com/documentation/guides/addresses

Everything in the database has a readable address, the same one the website uses, and every response gives you the addresses of what it mentions.

#### Matches

A match is its start date and both teams, as they are recorded: `2026-09-17-sri-lanka-v-england`. Women's matches end in `-women`.

#### Players, teams, grounds and competitions

The rest are their names in lower case, with anything that is not a letter or digit turned into a dash: `je-root`, `england`, `sophia-gardens`, `t20-blast`. A ground uses its name and, where the name does not already include it, its city.

When two players, teams or grounds share a name, each gets a short code on the end, `rashid-khan-px3skmvt3`, so no address is ever ambiguous. Once given, an address does not change.

#### Seasons

A season is written with a dash for a slash: 2025, or 2025-26 for a season that spans the new year.

Not sure of an address? `/v1/search?q=` returns the addresses of everything matching a name.

### Deliveries and extras

How a ball is numbered, what counts as legal, and how wides, no-balls, byes and leg-byes are recorded.

Address: https://cricketdatabase.com/documentation/guides/deliveries

Every ball bowled is one delivery, in order within its innings. `/v1/matches/{match}/deliveries` returns them all, and each carries where it sits in the over, who faced it, who bowled it, and what it scored.

#### Numbering

`over` is the over the ball belongs to, counting from 1. `ball` counts the legal balls bowled in that over so far, so a wide or a no-ball does not move it on: an over with a wide in it has seven deliveries but still only six legal balls.

`batter` faced the ball and `partner` was at the other end. Deliveries come in the order they were bowled. Use that order to sequence them, rather than rebuilding it from `over` and `ball`.

#### Runs

`runs.batter` is what the batter scored off the bat, `runs.extras` what the ball gave away otherwise, and `runs.total` the two together. Where there were extras, `extras` names them: `wides`, `no_balls`, `byes`, `leg_byes` or `penalty`, each only when it is not zero.

A four or a six that was run rather than hit to the boundary carries `all_run: true`. The analytical endpoints leave those out of their boundary counts.

#### Wickets

A ball that took a wicket has a `wickets` list, almost always of one: `how_out` (caught, bowled, lbw, run out, stumped and so on), who was `dismissed`, and who it was `fielded_by`. A run out can dismiss the `partner`, the batter at the other end, so always read `dismissed` rather than assuming the batter.

#### Players

Names come once, in the `players` dictionary at the top, keyed by address. Each ball carries only the addresses, which keeps a Test match to a manageable size.

#### By plan

The free key gets the first over of any match as a sample. Match Week gets every ball of the last 7 days, and Archive and Analyst Pro every ball since December 2001. The response says how many balls were `held_back`.

### Scorecards and dismissals

Batting, bowling, fall of wickets and how each kind of dismissal reads.

Address: https://cricketdatabase.com/documentation/guides/scorecards

`/v1/matches/{match}/scorecard` returns every innings of a match, in the order they were batted, the way a printed scorecard reads.

#### Batting

Each batter has their `runs`, `balls`, `fours` and `sixes`, whether they were `out`, and a `dismissal` written as a scorecard writes it: `c Buttler b Archer`, `lbw b Rashid`, `run out (Stokes)`, or `not out`. Those who did not bat are listed separately.

#### Fall of wickets

`fall_of_wickets` gives each wicket's number, the score when it fell and the batter out. Retirements are not counted as wickets.

#### Bowling

Each bowler has their `overs` as a string (`"3.4"` is three overs and four balls), `maidens`, `runs`, `wickets`, `economy` and `dots`, and the `wides` and `no_balls` they gave away. Byes and leg-byes are not charged to the bowler, as on a scorecard.

#### Extras

An innings carries its total `extras` and a `extras_detail` line breaking them down.

### Formats and competitions

The six formats, and how a competition keeps one address across its sponsors' names.

Address: https://cricketdatabase.com/documentation/guides/formats

Every match belongs to one of six formats, and the `format` filter uses the same names everywhere.

| format | What it is |
|---|---|
| `test` | Test matches |
| `odi` | One-day internationals |
| `t20i` | Twenty20 internationals, men's and women's |
| `t20` | Twenty20 leagues and domestic T20, such as the IPL and the T20 Blast |
| `multi-day` | Domestic first-class cricket, such as the County Championship and the Sheffield Shield |
| `one-day` | Domestic one-day cricket, such as the One-Day Cup |

#### One competition, one address

Competitions change their names with their sponsors. Each match is recorded under the name used at the time, so the T20 Blast appears as NatWest T20 Blast, Vitality Blast and Vitality Blast Men. We fold those together under one address, `t20-blast`, and each competition lists the names it was filed under as `also_filed_as`. Filtering matches by `competition` therefore gives you every season, whatever it was called.

### Players and their names

Name variants, and who counts as a player.

Address: https://cricketdatabase.com/documentation/guides/players

Players are named by initials and surname, such as `JE Root` or `V Kohli`, and full names where that is how a player is known, such as `Babar Azam`.

#### Other names

A player can be recorded under more than one name over a career. Search looks at all of them, so `/v1/search?q=` finds a player by any name they have been recorded under, and returns the one address that belongs to them.

#### Who counts as a player

Only people who have played in a match have player addresses. Umpires and referees appear by name on match pages but do not have player pages.

### Limits and headers

Two limits per plan, calls a minute and calls a day, what counts, when each resets and the headers that tell you.

Address: https://cricketdatabase.com/documentation/guides/limits

Each plan has two limits: calls a minute, which keeps the pace even, and calls a day, the quota. Only successful calls count against the quota; an error does not use one up, and `/v1/usage` never does.

| Plan | Calls a minute | Calls a day |
|---|---|---|
| Free key | 10 | 50 |
| Match Week | 60 | 5,000 |
| Archive | 120 | 25,000 |
| Pro | 180 | 50,000 |
| Analyst Pro | 300 | 100,000 |

#### When they reset

The minute resets on the minute; the day at midnight UTC. `/v1/usage` shows today's and this month's calls, both limits, what is left and when each resets.

#### The headers

Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the minute (the reset as a Unix time), `X-Quota-Limit`, `X-Quota-Remaining` and `X-Quota-Reset` for the day, and `X-Plan`. Read them rather than counting yourself.

#### Too fast, or out for the day

Two different answers, both 429 with a `Retry-After` in seconds. `rate_limited` means slow down: wait the few seconds and carry on. `quota_exceeded` means the day's calls are used: it says when they reset, and `/pricing` has the plans with more.

### Errors

One error shape, nine codes, and what to do about each.

Address: https://cricketdatabase.com/documentation/guides/errors

Every error has the same shape:

0
Decide what to do from `code`, which does not change; `message` is for people and may be reworded.

| Status | Code | What to do |
|---|---|---|
| 400 | `bad_request` | Fix the value the message names; a key in the address, or a method other than GET, also answers this |
| 401 | `unauthorized` | Send a current key; the message says whether it was missing, unknown or revoked |
| 403 | `upgrade_required` | `plan` names the plan that opens it |
| 404 | `not_found` | Check the address; search finds the right one |
| 404 | `no_ball_by_ball` | The match is held with its scorecard but not its balls (`coverage` `scorecard`): the scorecard call answers it, the deliveries, overs and partnerships calls do not; not counted against your day |
| 404 | `no_scorecard` | The match is held without its scorecard (`coverage` `totals` or `result_only`): ask for the match itself, which answers with its innings totals or its result; not counted against your day |
| 422 | `unknown_parameter` | Drop or correct the parameter named; `allowed` lists the ones this endpoint takes |
| 429 | `rate_limited` | Too fast: wait for `Retry-After`, a few seconds |
| 429 | `quota_exceeded` | The day's calls are used: wait for midnight UTC, or move to a larger plan |
| 500 | `server_error` | Try again later; it has been logged |

### Paging

page or cursor, per_page, and walking a long list politely.

Address: https://cricketdatabase.com/documentation/guides/paging

Endpoints that return lists page them. Ask with `page` (from 1) and `per_page` (1 to 100, default 50), or follow a `cursor`. If both are sent, `page` wins.

0
A first call gives the whole picture: `total`, `total_pages` and the pages either side. Matches and innings come newest first, so page 1 is always the latest.

#### Walking a long list

Pass `next_cursor` back as `cursor` until it comes back `null`. A cursor call returns only `count` and `next_cursor`, which keeps later pages quick. Each page is one call against your daily quota, so a larger `per_page` costs fewer calls; filters (a `year`, a `format`, a `competition`) keep lists short.

### Data freshness

When new matches arrive, and how to know what you are looking at is current.

Address: https://cricketdatabase.com/documentation/guides/freshness

New matches are added once a day. The update runs at 03:15 UTC, and a full re-check of every match runs each Sunday at 04:40 UTC to pick up corrections.

#### How recent is recent

A match is added once its ball-by-ball record is complete, which is usually within a few days of the match. So the database is not live scoring: yesterday's match may not be in yet.

#### Knowing what you have

`/v1/status` gives `latest_update`, when the last update finished, and `latest_match`, the date of the newest match held. `/v1/results/yesterday` returns the newest day in the database, whatever its date.

#### Today's matches

Matches starting today are part of Match Week, Pro and Analyst Pro. The free key and Archive read up to yesterday: on those plans, lists stop at yesterday and a match from today answers `403 upgrade_required`, naming the plan that includes it.

### Coverage

What is in the database by format and year, and where the record has gaps.

Address: https://cricketdatabase.com/documentation/guides/coverage

The database holds 22,983 matches from December 2001 to today, every one ball by ball, across men's and women's cricket, internationals and the major leagues and domestic competitions.

#### Where the record has gaps

The database holds most, but not all, matches. For men's internationals since 2001 it holds about 85% of Tests and 81% of ODIs; the rest were never published ball by ball. Careers built from the database can therefore read a little below official records, and the website says so on every player page.

Since 3 October 2026 every men's Test, ODI and T20 international back to 1877 is listed as well, with its teams, ground, dates and result. The ones without their balls carry `coverage` `scorecard` when we hold every batter's and bowler's line as the scorer kept it, `totals` when we hold their innings totals, extras and fall of wickets, or `result_only`; ask `/v1/matches?coverage=totals` or `coverage=result_only` for them, or `coverage=full` for the matches with every ball.

#### What that means for you

Treat totals as totals of the matches held. Where an official figure matters, compare with it; where the ball-by-ball detail matters, nothing else has it for these matches.

### Use with Claude and agents

The agent skill and the MCP server: let Claude, Cursor or any agent look cricket up for you on your own key.

Address: https://cricketdatabase.com/documentation/guides/agents

Two ways let an AI agent use Cricket Database for you, both on your own key and plan. The agent skill is one file that teaches an agent which calls answer which questions, the limits and the errors. The [MCP server](https://cricketdatabase.com/mcp) gives the same calls as tools the agent can run.

#### The agent skill

[Download the agent skill](https://cricketdatabase.com/skill.md) (`SKILL.md`). For Claude Code, save it as `~/.claude/skills/cricketdatabase/SKILL.md`; for Claude in the app, upload it as a skill in Claude's settings. Agents that look for skills by themselves find it at `https://cricketdatabase.com/.well-known/agent-skills/index.json`.

#### The MCP server

Add `https://api.cricketdatabase.com/mcp` to your client with your key as `Authorization: Bearer ...`. [The MCP page](https://cricketdatabase.com/mcp) has the setup for each client and the list of tools.

#### What the agent can reach

Exactly what your plan reaches: every tool call is one API call and counts as one. The free key gives the last 30 days in full and samples of older matches; see [What each plan can call](https://cricketdatabase.com/documentation/guides/plans).

### MCP server

The API as tools for an assistant: add one address and your key, and Claude, Cursor or any MCP client looks cricket up for you.

Address: https://cricketdatabase.com/documentation/guides/mcp

The MCP server is `https://cricketdatabase.com/mcp`. Each of its tools is one call to the API with your own key, so an assistant gets exactly what your plan gets, and each tool call counts as one call. The [MCP tools](https://cricketdatabase.com/documentation/mcp-tools) page lists them all.

#### Claude Code

0

#### Cursor

In `.cursor/mcp.json`:

1

#### Other clients

Any client that takes a streamable HTTP server with a header works the same way: the address above, and `Authorization: Bearer YOUR_KEY`. The Claude and ChatGPT apps add servers through a sign-in rather than a key; until that sign-in is in place, use a client that takes the header.

#### A worked example

Ask "Who top-scored in yesterday's internationals?". The assistant calls `latest_results` for the day's matches, then `get_scorecard` for each one, and answers from the batting cards: three tool calls, three API calls.

#### When a tool is not on your plan

It answers with the plan that has it and a link to [pricing](https://cricketdatabase.com/pricing), so the assistant can tell you, rather than failing. A pace limit is worded as one, not as an outage.

## Errors

Every failure answers `{"error": {"code", "message", "docs"}}` with a code that never changes: `bad_request`, `unknown_parameter`, `unauthorized`, `upgrade_required`, `not_found`, `no_scorecard`, `no_ball_by_ball`, `rate_limited`, `quota_exceeded` and `server_error`. The full list, with what to do for each: https://cricketdatabase.com/documentation/guides/errors

## About this document

Generated from the API's endpoint list, its guides and its plan settings, so it always matches the API. The date at the top is the newest change to those sources: two copies with the same date are the same. Machine-readable alternatives: https://cricketdatabase.com/openapi.json, https://cricketdatabase.com/postman-collection.json and the MCP server at https://cricketdatabase.com/mcp.