{ "openapi": "3.1.0", "info": { "title": "Cricket Database API", "version": "1.0.0", "description": "Ball-by-ball cricket data since December 2001: matches, scorecards, deliveries, players, teams, grounds, competitions, records and analytics.", "contact": { "url": "https://cricketdatabase.com/documentation" }, "termsOfService": "https://cricketdatabase.com/terms" }, "servers": [ { "url": "https://api.cricketdatabase.com/v1" } ], "security": [ { "Bearer": [] }, { "ApiKey": [] } ], "paths": { "/usage": { "get": { "operationId": "usage", "tags": [ "Account and reference" ], "summary": "Usage", "description": "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. Documentation: https://cricketdatabase.com/documentation/usage", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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-12T22:36:00Z" }, "key": { "prefix": "cdb_live_doc", "label": "Documentation", "created_at": "2026-10-12T22:35:12Z", "last_used_at": null } }, "meta": { "plan": "plus", "window": { "from": "2001-12-01", "to": "today", "ball_by_ball": "every match", "analytics": true } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/status": { "get": { "operationId": "status", "tags": [ "Account and reference" ], "summary": "Status", "description": "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. Documentation: https://cricketdatabase.com/documentation/status", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "ok": true, "matches": 23860, "deliveries": 11986386, "people": 19427, "competitions": 1185, "latest_update": "2026-10-12T22:22:19Z", "latest_match": "2026-10-11" }, "meta": {} } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "security": [] } }, "/search": { "get": { "operationId": "search", "tags": [ "Account and reference" ], "summary": "Search", "description": "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. Documentation: https://cricketdatabase.com/documentation/search", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "q": "root", "players": [ { "player": "je-root", "name": "JE Root", "matches": 516 }, { "player": "wt-root", "name": "WT Root", "matches": 184 }, "... 3 more" ], "teams": [], "venues": [], "competitions": [] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "At least 2 characters", "schema": { "type": "string" } } ] } }, "/matches": { "get": { "operationId": "matches", "tags": [ "Matches" ], "summary": "Matches", "description": "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. Documentation: https://cricketdatabase.com/documentation/matches", "x-plans": { "free": "window30", "match-week": "window30", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "date", "in": "query", "required": false, "description": "One day, YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "On or after", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "On or before", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "A calendar year", "schema": { "type": "integer" } }, { "name": "month", "in": "query", "required": false, "description": "With year, 1 to 12", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "male or female", "schema": { "type": "string" } }, { "name": "team", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "venue", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "competition", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "coverage", "in": "query", "required": false, "description": "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", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1 to 100 (default 50)", "schema": { "type": "integer" } } ] } }, "/matches/{match}": { "get": { "operationId": "match", "tags": [ "Matches" ], "summary": "Match", "description": "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. Documentation: https://cricketdatabase.com/documentation/match", "x-plans": { "free": "window30", "match-week": "window30", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/matches/{match}/scorecard": { "get": { "operationId": "scorecard", "tags": [ "Matches" ], "summary": "Scorecard", "description": "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. Documentation: https://cricketdatabase.com/documentation/scorecard", "x-plans": { "free": "window30", "match-week": "window30", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 8 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" }, "... 7 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 }, "... 4 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 }, "... 4 more" ], "did_not_bat": [ { "player": "j-overton", "name": "J Overton" }, { "player": "la-dawson", "name": "LA Dawson" }, "... 3 more" ], "fall_of_wickets": [ { "wicket": 1, "runs": 51, "player": "AHT Donald" }, { "wicket": 2, "runs": 55, "player": "JC Buttler" }, "... 2 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 }, "... 3 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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/matches/{match}/deliveries": { "get": { "operationId": "deliveries", "tags": [ "Matches" ], "summary": "Deliveries", "description": "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. Documentation: https://cricketdatabase.com/documentation/deliveries", "x-plans": { "free": "sample", "match-week": "window7", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } }, "... 198 more" ] }, "meta": { "plan": "plus", "held_back": 0 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/matches/{match}/overs": { "get": { "operationId": "overs", "tags": [ "Matches" ], "summary": "Overs", "description": "Over by over: runs, wickets, extras, the running total and the bowler. Plans: Free key not included, Match Week last 7 days, Archive to yesterday, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/overs", "x-plans": { "free": "none", "match-week": "window7", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } }, "... 31 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/matches/{match}/partnerships": { "get": { "operationId": "partnerships", "tags": [ "Matches" ], "summary": "Partnerships", "description": "Every partnership, worked out from the balls: the pair, runs, balls and how it ended. Plans: Free key not included, Match Week last 7 days, Archive to yesterday, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/partnerships", "x-plans": { "free": "none", "match-week": "window7", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 12 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/matches/{match}/reviews": { "get": { "operationId": "reviews", "tags": [ "Matches" ], "summary": "DRS reviews", "description": "Every DRS review: the ball, who asked, the batter, the umpire, the decision and umpire's call. Plans: Free key not included, Match Week last 7 days, Archive to yesterday, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/reviews", "x-plans": { "free": "none", "match-week": "window7", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "match": "2026-09-17-sri-lanka-v-england", "reviews": [] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/results/yesterday": { "get": { "operationId": "results_yesterday", "tags": [ "Matches" ], "summary": "Latest results", "description": "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. Documentation: https://cricketdatabase.com/documentation/results-yesterday", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 2 more" ] }, "meta": { "plan": "plus", "count": 4 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/live": { "get": { "operationId": "live", "tags": [ "Live" ], "summary": "Live matches", "description": "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: Free key not included, Match Week in full, Archive not included, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/live", "x-plans": { "free": "none", "match-week": "full", "archive": "none", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "count": 59, "results": [ { "match": "2026-10-09-afghanistan-v-bangladesh", "name": "Afghanistan v Bangladesh", "competition": "Bangladesh tour of United Arab Emirates 2026/27", "format": "Test", "state": "live", "international": true, "women": false, "status": "Afghanistan require 347 runs", "starts_at": "2026-10-09T06:00:00Z", "venue": "Zayed Cricket Stadium, Abu Dhabi", "city": "Abu Dhabi", "teams": [ { "name": "Afghanistan", "score": "240 & 132/3 (50 ov, target 479)" }, { "name": "Bangladesh", "score": "346 & 372/7d" } ], "innings": [ { "innings": 1, "team": "Bangladesh", "runs": 346, "wickets": 10, "overs": "92.3", "chase_target": null, "innings_declared": false }, { "innings": 2, "team": "Bangladesh", "runs": 0, "wickets": 0, "overs": "89.1", "chase_target": null, "innings_declared": false }, "... 2 more" ], "ball_by_ball": true, "batting": "Bangladesh", "winner": null, "updated_at": "2026-10-12T22:34:07Z" }, { "match": "2026-10-09-south-africa-v-australia", "name": "South Africa v Australia", "competition": "Australia tour of South Africa 2026/27", "format": "Test", "state": "live", "international": true, "women": false, "status": "South Africa require 319 runs", "starts_at": "2026-10-09T07:30:00Z", "venue": "Kingsmead, Durban", "city": "Durban", "teams": [ { "name": "South Africa", "score": "284 & 102/4 (41 ov, target 421)" }, { "name": "Australia", "score": "390 & 314/6d" } ], "innings": [ { "innings": 1, "team": "Australia", "runs": 390, "wickets": 10, "overs": "137.2", "chase_target": null, "innings_declared": false }, { "innings": 2, "team": "Australia", "runs": 0, "wickets": 0, "overs": "78", "chase_target": null, "innings_declared": false }, "... 2 more" ], "ball_by_ball": true, "batting": "Australia", "winner": null, "updated_at": "2026-10-12T22:34:03Z" }, "... 57 more" ] }, "meta": { "plan": "plus", "window": { "updated_every": "1 minute", "last_update": "2026-10-12T22:35:04Z" }, "count": 59 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "state", "in": "query", "required": false, "description": "live (the default), upcoming, finished or all", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "Test, ODI, T20I, T20, First-class, List A", "schema": { "type": "string" } }, { "name": "international", "in": "query", "required": false, "description": "true for Tests, ODIs and T20 internationals only", "schema": { "type": "string" } } ] } }, "/live/{match}": { "get": { "operationId": "live_match", "tags": [ "Live" ], "summary": "A live match", "description": "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: Free key not included, Match Week in full, Archive not included, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/live-match", "x-plans": { "free": "none", "match-week": "full", "archive": "none", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "match": "2026-10-09-afghanistan-v-bangladesh", "name": "Afghanistan v Bangladesh", "competition": "Bangladesh tour of United Arab Emirates 2026/27", "format": "Test", "state": "live", "international": true, "women": false, "status": "Afghanistan require 347 runs", "starts_at": "2026-10-09T06:00:00Z", "venue": "Zayed Cricket Stadium, Abu Dhabi", "city": "Abu Dhabi", "teams": [ { "name": "Afghanistan", "score": "240 & 132/3 (50 ov, target 479)" }, { "name": "Bangladesh", "score": "346 & 372/7d" } ], "innings": [ { "innings": 1, "team": "Bangladesh", "runs": 346, "wickets": 10, "overs": "92.3", "chase_target": null, "innings_declared": false }, { "innings": 2, "team": "Bangladesh", "runs": 0, "wickets": 0, "overs": "89.1", "chase_target": null, "innings_declared": false }, "... 2 more" ], "ball_by_ball": true, "batting": "Bangladesh", "winner": null, "updated_at": "2026-10-12T22:34:07Z", "toss": "Bangladesh , elected to bat first", "scorecard": [ { "innings": 1, "team": "Bangladesh", "runs": 347, "wickets": 10, "overs": "92.3", "run_rate": 3.75, "extras": 9, "extras_detail": { "no_balls": 1, "byes": 4, "leg_byes": 4 }, "batting": [ { "player": "shadman-islam", "name": "Shadman Islam", "runs": 66, "balls": 115, "fours": 7, "sixes": 0, "out": true, "how_out": "caught", "dismissal": "c Zia-ur-Rehman b Mohammad Saleem", "strike_rate": 57.4 }, { "player": "tanzid-hasan", "name": "Tanzid Hasan", "runs": 83, "balls": 71, "fours": 8, "sixes": 4, "out": true, "how_out": "caught", "dismissal": "c Ikram Alikhil b Ismat Alam", "strike_rate": 116.9 }, "... 9 more" ], "bowling": [ { "player": "yamin-ahmadzai", "name": "Yamin Ahmadzai", "overs": "20.3", "maidens": 3, "runs": 78, "wickets": 3, "economy": 3.8, "dots": 85, "fours": 7, "sixes": 2, "wides": 0, "no_balls": 0 }, { "player": "mohammad-saleem", "name": "Mohammad Saleem", "overs": "23", "maidens": 2, "runs": 79, "wickets": 4, "economy": 3.43, "dots": 96, "fours": 10, "sixes": 0, "wides": 0, "no_balls": 1 }, "... 4 more" ] }, { "innings": 2, "team": "Bangladesh", "runs": 242, "wickets": 10, "overs": "89.1", "run_rate": 2.71, "extras": 2, "extras_detail": { "no_balls": 1, "leg_byes": 1 }, "batting": [ { "player": "sediqullah-atal", "name": "Sediqullah Atal", "runs": 17, "balls": 32, "fours": 3, "sixes": 0, "out": true, "how_out": "caught", "dismissal": "c Najmul Hossain Shanto b Hasan Mahmud", "strike_rate": 53.1 }, { "player": "abdul-malik", "name": "Abdul Malik", "runs": 64, "balls": 120, "fours": 4, "sixes": 1, "out": true, "how_out": "caught", "dismissal": "c Litton Das b Ebadot Hossain", "strike_rate": 53.3 }, "... 9 more" ], "bowling": [ { "player": "hasan-mahmud", "name": "Hasan Mahmud", "overs": "21", "maidens": 5, "runs": 56, "wickets": 5, "economy": 2.67, "dots": 96, "fours": 5, "sixes": 1, "wides": 0, "no_balls": 1 }, { "player": "ebadat-hossain", "name": "Ebadot Hossain", "overs": "15.1", "maidens": 3, "runs": 55, "wickets": 4, "economy": 3.63, "dots": 60, "fours": 6, "sixes": 0, "wides": 0, "no_balls": 0 }, "... 4 more" ] }, "... 2 more" ], "now": { "innings": 4, "batting": [ { "player": "sediqullah-atal", "name": "Sediqullah Atal", "runs": 35, "balls": 126, "fours": 1, "sixes": 1, "strike_rate": 27.8, "on_strike": true }, { "player": "hashmatullah-shahidi", "name": "Hashmatullah Shahidi", "runs": 19, "balls": 27, "fours": 2, "sixes": 1, "strike_rate": 70.4, "on_strike": false } ], "bowler": { "player": "hasan-mahmud", "name": "Hasan Mahmud", "overs": "12", "maidens": 0, "runs": 31, "wickets": 1, "economy": 2.58 }, "over": { "over": 50, "ball": 6 }, "last_overs": [ { "over": 48, "bowler": "Hasan Mahmud", "balls": [ ".", "4", "... 4 more" ], "runs": 4 }, { "over": 49, "bowler": "Ebadot Hossain", "balls": [ "1", ".", "... 4 more" ], "runs": 5 }, "... 1 more" ], "partnership": { "runs": 22, "balls": 47 }, "run_rate": 2.64, "recent": [ "1", ".", "... 10 more" ], "chase": { "target": 479, "need": 347 } }, "last_ball": "Y2RiOmxiNDA0OTA2" }, "meta": { "plan": "plus", "window": { "updated_every": "1 minute", "last_update": "2026-10-12T22:35:04Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/live/{match}/balls": { "get": { "operationId": "live_balls", "tags": [ "Live" ], "summary": "Live deliveries", "description": "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: Free key not included, Match Week in full, Archive not included, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/live-balls", "x-plans": { "free": "none", "match-week": "full", "archive": "none", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "match": "2026-10-09-afghanistan-v-bangladesh", "count": 600, "deliveries": [ { "innings": 1, "over": 1, "ball": 1, "batter": { "player": "shadman-islam", "name": "Shadman Islam" }, "partner": { "player": "tanzid-hasan", "name": "Tanzid Hasan" }, "bowler": { "player": "yamin-ahmadzai", "name": "Yamin Ahmadzai" }, "runs": { "batter": 2, "extras": 0, "total": 2 } }, { "innings": 1, "over": 1, "ball": 2, "batter": { "player": "shadman-islam", "name": "Shadman Islam" }, "partner": { "player": "tanzid-hasan", "name": "Tanzid Hasan" }, "bowler": { "player": "yamin-ahmadzai", "name": "Yamin Ahmadzai" }, "runs": { "batter": 0, "extras": 0, "total": 0 } }, "... 598 more" ], "next": "Y2RiOmxiMjAwNzAy", "more": true }, "meta": { "plan": "plus", "window": { "updated_every": "1 minute", "last_update": "2026-10-12T22:35:04Z" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } }, { "name": "after", "in": "query", "required": false, "description": "The next value from an earlier answer", "schema": { "type": "string" } } ] } }, "/players": { "get": { "operationId": "players", "tags": [ "Players" ], "summary": "Players", "description": "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. Documentation: https://cricketdatabase.com/documentation/players", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": [ { "player": "v-kohli", "name": "V Kohli", "matches": 846 }, { "player": "a-kohli", "name": "A Kohli", "matches": 41 }, "... 5 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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Name, including recorded variants", "schema": { "type": "string" } }, { "name": "team", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "male or female", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1 to 100 (default 50)", "schema": { "type": "integer" } } ] } }, "/players/{player}": { "get": { "operationId": "player", "tags": [ "Players" ], "summary": "Player", "description": "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. Documentation: https://cricketdatabase.com/documentation/player", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 6 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } } ] } }, "/players/{player}/stats": { "get": { "operationId": "player_stats", "tags": [ "Players" ], "summary": "Career stats", "description": "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. Documentation: https://cricketdatabase.com/documentation/player-stats", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } } ] } }, "/players/{player}/innings": { "get": { "operationId": "player_innings", "tags": [ "Players" ], "summary": "Batting log", "description": "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. Documentation: https://cricketdatabase.com/documentation/player-innings", "x-plans": { "free": "sample", "match-week": "sample", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 48 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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1 to 100 (default 50)", "schema": { "type": "integer" } } ] } }, "/players/{player}/bowling": { "get": { "operationId": "player_bowling", "tags": [ "Players" ], "summary": "Bowling log", "description": "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. Documentation: https://cricketdatabase.com/documentation/player-bowling", "x-plans": { "free": "sample", "match-week": "sample", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 48 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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "", "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1 to 100 (default 50)", "schema": { "type": "integer" } } ] } }, "/teams": { "get": { "operationId": "teams", "tags": [ "Teams" ], "summary": "Teams", "description": "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. Documentation: https://cricketdatabase.com/documentation/teams", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "total": 428, "data": [ { "team": "india", "name": "India", "type": "international", "matches": 1409 }, { "team": "england", "name": "England", "type": "international", "matches": 1345 }, "... 426 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/teams/{team}": { "get": { "operationId": "team", "tags": [ "Teams" ], "summary": "Team", "description": "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. Documentation: https://cricketdatabase.com/documentation/team", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 8 more" ], "most_matches": [ { "player": "jc-buttler", "name": "JC Buttler", "matches": 424 }, { "player": "je-root", "name": "JE Root", "matches": 395 }, "... 8 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team address", "schema": { "type": "string" } } ] } }, "/teams/{team}/matches": { "get": { "operationId": "team_matches", "tags": [ "Teams" ], "summary": "Team matches", "description": "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. Documentation: https://cricketdatabase.com/documentation/team-matches", "x-plans": { "free": "window30", "match-week": "window30", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 48 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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team address", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "One day, YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "On or after", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "On or before", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "A calendar year", "schema": { "type": "integer" } }, { "name": "month", "in": "query", "required": false, "description": "With year, 1 to 12", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "male or female", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1 to 100 (default 50)", "schema": { "type": "integer" } } ] } }, "/teams/{team}/head-to-head/{other}": { "get": { "operationId": "head_to_head", "tags": [ "Teams" ], "summary": "Head to head", "description": "Two teams against each other, by format, with the last ten meetings. Plans: Free key not included, Match Week not included, Archive in full, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/head-to-head", "x-plans": { "free": "none", "match-week": "none", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 8 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team address", "schema": { "type": "string" } }, { "name": "other", "in": "path", "required": true, "description": "The other address", "schema": { "type": "string" } } ] } }, "/venues": { "get": { "operationId": "venues", "tags": [ "Venues" ], "summary": "Venues", "description": "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. Documentation: https://cricketdatabase.com/documentation/venues", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "total": 1040, "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 }, "... 1038 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/venues/{venue}": { "get": { "operationId": "venue", "tags": [ "Venues" ], "summary": "Venue", "description": "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. Documentation: https://cricketdatabase.com/documentation/venue", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 3 more" ], "most_runs": [ { "player": "ks-carlson", "name": "KS Carlson", "runs": 4951 }, { "player": "ca-ingram", "name": "CA Ingram", "runs": 4539 }, "... 3 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "venue", "in": "path", "required": true, "description": "The venue address", "schema": { "type": "string" } } ] } }, "/venues/{venue}/matches": { "get": { "operationId": "venue_matches", "tags": [ "Venues" ], "summary": "Venue matches", "description": "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. Documentation: https://cricketdatabase.com/documentation/venue-matches", "x-plans": { "free": "window30", "match-week": "window30", "archive": "toyesterday", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 48 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 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "venue", "in": "path", "required": true, "description": "The venue address", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "One day, YYYY-MM-DD", "schema": { "type": "string" } }, { "name": "from", "in": "query", "required": false, "description": "On or after", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "On or before", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "A calendar year", "schema": { "type": "integer" } }, { "name": "month", "in": "query", "required": false, "description": "With year, 1 to 12", "schema": { "type": "integer" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "male or female", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number, from 1", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page, 1 to 100 (default 50)", "schema": { "type": "integer" } } ] } }, "/competitions": { "get": { "operationId": "competitions", "tags": [ "Competitions" ], "summary": "Competitions", "description": "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. Documentation: https://cricketdatabase.com/documentation/competitions", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 1183 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/competitions/{competition}": { "get": { "operationId": "competition", "tags": [ "Competitions" ], "summary": "Competition", "description": "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. Documentation: https://cricketdatabase.com/documentation/competition", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 6 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 }, "... 6 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "competition", "in": "path", "required": true, "description": "The competition address", "schema": { "type": "string" } } ] } }, "/competitions/{competition}/seasons": { "get": { "operationId": "seasons", "tags": [ "Competitions" ], "summary": "Seasons", "description": "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. Documentation: https://cricketdatabase.com/documentation/seasons", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } }, "... 11 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "competition", "in": "path", "required": true, "description": "The competition address", "schema": { "type": "string" } } ] } }, "/competitions/{competition}/seasons/{season}": { "get": { "operationId": "season", "tags": [ "Competitions" ], "summary": "Season", "description": "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. Documentation: https://cricketdatabase.com/documentation/season", "x-plans": { "free": "full", "match-week": "full", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 16 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 }, "... 6 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 }, "... 6 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" }, "... 130 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "competition", "in": "path", "required": true, "description": "The competition address", "schema": { "type": "string" } }, { "name": "season", "in": "path", "required": true, "description": "The season address", "schema": { "type": "string" } } ] } }, "/records": { "get": { "operationId": "records", "tags": [ "Records" ], "summary": "Records", "description": "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. Documentation: https://cricketdatabase.com/documentation/records", "x-plans": { "free": "sample", "match-week": "sample", "archive": "full", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 98 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "type", "in": "query", "required": false, "description": "most-runs, most-wickets, highest-scores, best-bowling or team-totals", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day (default test)", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "male or female (default male)", "schema": { "type": "string" } } ] } }, "/analytics/matchups": { "get": { "operationId": "matchups", "tags": [ "Analytics" ], "summary": "Matchups", "description": "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. Documentation: https://cricketdatabase.com/documentation/matchups", "x-plans": { "free": "sample", "match-week": "sample", "archive": "sample", "pro": "sample", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "batter", "in": "query", "required": true, "description": "", "schema": { "type": "string" } }, { "name": "bowler", "in": "query", "required": true, "description": "", "schema": { "type": "string" } } ] } }, "/analytics/players/{player}/splits": { "get": { "operationId": "splits", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Splits", "description": "Batting by opposition, venue, year, innings and position; bowling by opposition, venue, year and innings. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/splits", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 28 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 }, "... 28 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 }, "... 13 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 }, "... 2 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 }, "... 5 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 }, "... 28 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 }, "... 28 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 }, "... 13 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 }, "... 2 more" ] } }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } } ] } }, "/analytics/players/{player}/phases": { "get": { "operationId": "phases", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Phases", "description": "Powerplay, middle and death: strike rate, dot and boundary rates and dismissals; bowling economy and wickets. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/phases", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "t20i, t20, odi or one-day (default t20)", "schema": { "type": "string" } } ] } }, "/analytics/players/{player}/dismissals": { "get": { "operationId": "dismissals", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Dismissals", "description": "How a player gets out: by kind, by bowler and by balls faced. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/dismissals", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 4 more" ], "by_bowler": [ { "player": "pj-cummins", "name": "PJ Cummins", "count": 16 }, { "player": "jj-bumrah", "name": "JJ Bumrah", "count": 15 }, "... 8 more" ], "by_balls_faced": [ { "balls": "0-9", "count": 94 }, { "balls": "10-19", "count": 97 }, "... 4 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } } ] } }, "/analytics/players/{player}/scoring": { "get": { "operationId": "scoring", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Scoring shape", "description": "Scoring shape: the share of dots, singles, twos, threes, fours and sixes, boundary runs and sixes per 100 balls. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/scoring", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } } ] } }, "/analytics/players/{player}/form": { "get": { "operationId": "form", "tags": [ "Analytics" ], "summary": "Rolling form", "description": "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. Documentation: https://cricketdatabase.com/documentation/form", "x-plans": { "free": "sample", "match-week": "sample", "archive": "sample", "pro": "sample", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 18 more" ] }, "meta": { "plan": "plus", "window": 5 } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "player", "in": "path", "required": true, "description": "The player address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "test, odi, t20i, t20, multi-day, one-day", "schema": { "type": "string" } }, { "name": "innings", "in": "query", "required": false, "description": "5 to 100 (default 20)", "schema": { "type": "integer" } }, { "name": "window", "in": "query", "required": false, "description": "2 to 20 (default 5)", "schema": { "type": "integer" } } ] } }, "/analytics/venues/{venue}/par-scores": { "get": { "operationId": "par_scores", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Par scores", "description": "First-innings totals by format and year: average, median, highest, lowest, and batting first against chasing. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/par-scores", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 11 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 }, "... 10 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 }, "... 3 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 }, "... 4 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 }, "... 3 more" ] } } }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "venue", "in": "path", "required": true, "description": "The venue address", "schema": { "type": "string" } } ] } }, "/analytics/venues/{venue}/toss": { "get": { "operationId": "toss", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Toss effect", "description": "How often the toss winner bats, and how often they win after batting or fielding. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/toss", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "venue", "in": "path", "required": true, "description": "The venue address", "schema": { "type": "string" } } ] } }, "/analytics/teams/{team}/phases": { "get": { "operationId": "team_phases", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Team phases", "description": "A team's run rate and wickets by phase, batting and bowling, year by year. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/team-phases", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 } } }, "... 20 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "team", "in": "path", "required": true, "description": "The team address", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "t20i, t20, odi or one-day (default t20)", "schema": { "type": "string" } } ] } }, "/analytics/competitions/{competition}/trends": { "get": { "operationId": "trends", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Competition trends", "description": "Season by season: first-innings average, run rate, runs per wicket, boundaries per match and chase wins. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/trends", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 11 more" ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "competition", "in": "path", "required": true, "description": "The competition address", "schema": { "type": "string" } } ] } }, "/analytics/chases": { "get": { "operationId": "chases", "tags": [ "Analytics" ], "summary": "[Analyst Pro] Chases", "description": "Chase success by target band. Rain-affected chases are left out. Plans: Free key not included, Match Week not included, Archive not included, Pro not included, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/chases", "x-plans": { "free": "none", "match-week": "none", "archive": "none", "pro": "none", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 13 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." } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "format", "in": "query", "required": false, "description": "t20i, t20, odi or one-day (default t20i)", "schema": { "type": "string" } }, { "name": "gender", "in": "query", "required": false, "description": "male or female", "schema": { "type": "string" } }, { "name": "competition", "in": "query", "required": false, "description": "", "schema": { "type": "string" } }, { "name": "venue", "in": "query", "required": false, "description": "", "schema": { "type": "string" } } ] } }, "/analytics/matches/{match}/worm": { "get": { "operationId": "worm", "tags": [ "Analytics" ], "summary": "Worm", "description": "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. Documentation: https://cricketdatabase.com/documentation/worm", "x-plans": { "free": "sample", "match-week": "sample", "archive": "sample", "pro": "sample", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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 }, "... 18 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 }, "... 11 more" ] } ] }, "meta": { "plan": "plus" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/analytics/matches/{match}/win-probability": { "get": { "operationId": "win_probability", "tags": [ "Analytics" ], "summary": "Win probability", "description": "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. Documentation: https://cricketdatabase.com/documentation/win-probability", "x-plans": { "free": "sample", "match-week": "sample", "archive": "sample", "pro": "sample", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "path", "required": true, "description": "The match address", "schema": { "type": "string" } } ] } }, "/export": { "get": { "operationId": "export", "tags": [ "Bulk files" ], "summary": "Bulk files", "description": "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: Free key not included, Match Week not included, Archive to yesterday, Pro to yesterday, Analyst Pro to yesterday. Documentation: https://cricketdatabase.com/documentation/export", "x-plans": { "free": "none", "match-week": "none", "archive": "toyesterday", "pro": "toyesterday", "plus": "toyesterday" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" }, "... 24 more" ], "count": 26, "built_at": "2026-10-10T07:04:46Z", "up_to": "2026-10-09", "years": { "from": 2001, "to": 2026 }, "tables": [ "matches", "innings", "... 6 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." } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "table", "in": "query", "required": false, "description": "matches, innings, batting, bowling, deliveries, players, teams or grounds", "schema": { "type": "string" } }, { "name": "year", "in": "query", "required": false, "description": "Four digits, such as 2019", "schema": { "type": "string" } }, { "name": "format", "in": "query", "required": false, "description": "csv or jsonl", "schema": { "type": "string" } } ] } }, "/live/stream": { "get": { "operationId": "live_stream", "tags": [ "Live" ], "summary": "Live stream", "description": "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: Free key not included, Match Week in full, Archive not included, Pro in full, Analyst Pro in full. Documentation: https://cricketdatabase.com/documentation/live-stream", "x-plans": { "free": "none", "match-week": "full", "archive": "none", "pro": "full", "plus": "full" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "data": { "stream": "text/event-stream", "events": { "snapshot": "every match in play on connect, as /v1/live gives it", "score": "a match whose score or state changed (one /v1/live row)", "ball": "one new ball, as /v1/live/{match}/balls gives it, with its match" }, "matches_in_play": [ { "match": "2026-10-09-afghanistan-v-bangladesh", "name": "Afghanistan v Bangladesh", "competition": "Bangladesh tour of United Arab Emirates 2026/27", "format": "Test", "state": "live", "international": true, "women": false, "status": "Afghanistan require 347 runs", "starts_at": "2026-10-09T06:00:00Z", "venue": "Zayed Cricket Stadium, Abu Dhabi", "city": "Abu Dhabi", "teams": [ { "name": "Afghanistan", "score": "240 & 132/3 (50 ov, target 479)" }, { "name": "Bangladesh", "score": "346 & 372/7d" } ], "innings": [ { "innings": 1, "team": "Bangladesh", "runs": 346, "wickets": 10, "overs": "92.3", "chase_target": null, "innings_declared": false }, { "innings": 2, "team": "Bangladesh", "runs": 0, "wickets": 0, "overs": "89.1", "chase_target": null, "innings_declared": false }, "... 2 more" ], "ball_by_ball": true, "batting": "Bangladesh", "winner": null, "updated_at": "2026-10-12T22:34:07Z" }, { "match": "2026-10-09-south-africa-v-australia", "name": "South Africa v Australia", "competition": "Australia tour of South Africa 2026/27", "format": "Test", "state": "live", "international": true, "women": false, "status": "South Africa require 319 runs", "starts_at": "2026-10-09T07:30:00Z", "venue": "Kingsmead, Durban", "city": "Durban", "teams": [ { "name": "South Africa", "score": "284 & 102/4 (41 ov, target 421)" }, { "name": "Australia", "score": "390 & 314/6d" } ], "innings": [ { "innings": 1, "team": "Australia", "runs": 390, "wickets": 10, "overs": "137.2", "chase_target": null, "innings_declared": false }, { "innings": 2, "team": "Australia", "runs": 0, "wickets": 0, "overs": "78", "chase_target": null, "innings_declared": false }, "... 2 more" ], "ball_by_ball": true, "batting": "Australia", "winner": null, "updated_at": "2026-10-12T22:34:03Z" }, "... 24 more" ] }, "meta": { "plan": "plus", "note": "The call itself answers a stream of events; this is what its first event carries." } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "match", "in": "query", "required": false, "description": "A live match address from /v1/live; leave out for every match in play", "schema": { "type": "string" } } ] } }, "/export/{file}": { "get": { "operationId": "export_file", "tags": [ "Bulk files" ], "summary": "Download a bulk file", "description": "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: Free key not included, Match Week not included, Archive to yesterday, Pro to yesterday, Analyst Pro to yesterday. Documentation: https://cricketdatabase.com/documentation/export-file", "x-plans": { "free": "none", "match-week": "none", "archive": "toyesterday", "pro": "toyesterday", "plus": "toyesterday" }, "responses": { "200": { "description": "OK", "content": { "application/json": { "example": { "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" } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "403": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } }, "parameters": [ { "name": "file", "in": "path", "required": true, "description": "The file address", "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer" }, "ApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "responses": { "Error": { "description": "An error. See https://cricketdatabase.com/documentation/guides/errors", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unknown_parameter", "unauthorized", "upgrade_required", "not_found", "no_scorecard", "rate_limited", "quota_exceeded", "server_error" ] }, "message": { "type": "string" }, "plan": { "type": "string" }, "docs": { "type": "string" } } } } } } } } } } }