Matches
GET
/v1/matchesOn each planFree keyLast 30 daysMatch WeekLast 30 daysArchiveTo yesterdayProIn fullAnalyst ProIn fullMCP toolsearch_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.
Parameters
| Name | In | Values | Required |
|---|---|---|---|
date | query | One day, YYYY-MM-DD | |
from | query | On or after | |
to | query | On or before | |
year | query | A calendar year | |
month | query | With year, 1 to 12 | |
format | query | test, odi, t20i, t20, multi-day, one-day | |
gender | query | male or female | |
team | query | ||
venue | query | ||
competition | query | ||
coverage | query | 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 | Page number, from 1 | |
limit | query | Results per page, 1 to 100 (default 50) |
Request
curl -H "Authorization: Bearer $CDB_KEY" \ "https://api.cricketdatabase.com/v1/matches?format=test&year=2025"
import requests
r = requests.get("https://api.cricketdatabase.com/v1/matches?format=test&year=2025",
headers={"Authorization": f"Bearer {key}"})
print(r.json())const r = await fetch("https://api.cricketdatabase.com/v1/matches?format=test&year=2025",
{ headers: { "Authorization": `Bearer ${key}` } });
console.log(await r.json());curl -H "X-API-Key: $CDB_KEY" \ "https://api.cricketdatabase.com/v1/matches?format=test&year=2025"
import requests
r = requests.get("https://api.cricketdatabase.com/v1/matches?format=test&year=2025",
headers={"X-API-Key": key})
print(r.json())const r = await fetch("https://api.cricketdatabase.com/v1/matches?format=test&year=2025",
{ headers: { "X-API-Key": key } });
console.log(await r.json());Response
{
"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"
},
"... 41 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
}
}A real response from the database for the example request, on a Analyst Pro key. Lists are cut to their first two items.