How do I get cricket ball-by-ball data in Python?
Every delivery of a match: batter, bowler, runs, extras, the wicket and fielders, the score after the ball and our win probability.
Code verified November 3, 2026. One call to get_deliveries, 10 credits.
The call
match_id comes from get_matches. Overs are 0-based as scorers count them; ball counts wides and no-balls, legal says whether it counted.
import requests
import pandas as pd
API_KEY = "YOUR_API_KEY"
resp = requests.post(
"https://mcp.yorkerapi.com/v1/get_deliveries",
headers={"x-api-key": API_KEY},
json={
"match_id": "1473511",
"innings": 2,
},
timeout=60,
)
resp.raise_for_status()
data = resp.json()["data"]
balls = pd.DataFrame(data["deliveries"])
by_over = balls.groupby("over").agg(runs=("runs_total", "sum"), wickets=("wicket_kind", "count"), win_prob=("win_prob", "last"))
print(by_over.tail(5))
print(balls[balls.wicket_kind.notna()][["delivery", "batter", "bowler", "wicket_kind", "team_runs"]])
Replace YOUR_API_KEY with a key from your dashboard. Python needs requests and pandas (pip install requests pandas). JavaScript runs on Node 18 or newer, or in the browser.
What comes back
The data object of the response, trimmed to the first rows. Every field is real output from the run above.
{
"deliveries": [
{
"match_id": "1473511",
"date": "2025-06-03",
"innings": 2,
"over": 0,
"ball": 1,
"delivery": "0.1",
"legal": true,
"batter_id": "b5797845",
"batter": "Priyansh Arya",
"bowler_id": "2e81a32d",
"bowler": "B Kumar",
"non_striker_id": "9418198b",
"runs_batter": 4,
"runs_extras": 0,
"runs_total": 4,
"wides": null,
"noballs": null,
"byes": null,
"legbyes": null,
"penalty": null,
"non_boundary": null,
"wicket_kind": null,
"player_out_id": null,
"fielder_ids": null,
"review": null,
"team_runs": 4,
"team_wickets": 0,
"team_legal_balls": 1,
"win_prob": 0.5801
},
{
"match_id": "1473511",
"date": "2025-06-03",
"innings": 2,
"over": 0,
"ball": 2,
"delivery": "0.2",
"legal": true,
"batter_id": "b5797845",
"batter": "Priyansh Arya",
"bowler_id": "2e81a32d",
"bowler": "B Kumar",
"non_striker_id": "9418198b",
"runs_batter": 1,
"runs_extras": 0,
"runs_total": 1,
"wides": null,
"noballs": null,
"byes": null,
"legbyes": null,
"penalty": null,
"non_boundary": null,
"wicket_kind": null,
"player_out_id": null,
"fielder_ids": null,
"review": null,
"team_runs": 5,
"team_wickets": 0,
"team_legal_balls": 2,
"win_prob": 0.5674
},
"...121 more"
],
"count": 123,
"next_offset": null
}What to do next
- get_match (5 credits). The same match as batting and bowling cards, with each book's opening and closing price.
- get_win_probability (10 credits). The win-probability worm over by over and the balls that swung it.
More guides
Start with 500 free credits every month
No card. REST or MCP.