Every ball, one request away.
OpenCricketAPI exposes matches, scorecards, ball-by-ball deliveries, partnerships, phase splits and player matchups through a clean REST interface and an MCP server.
Find a season's matches
curl "https://opencricketapi.com/v1/matches?competition=comp_indian-premier-league&season=2026" \
-H "Accept: application/json" \
-H "Authorization: Bearer oc_live_your_api_key"Then open one match
{
"data": {
"id": "match_cs_1535465",
"date": "2026-05-31",
"end_date": "2026-05-31",
"season": "2026",
"competition": {
"id": "comp_indian-premier-league",
"name": "Indian Premier League"
},
"event_name": "Indian Premier League",
"stage": "Final",
"format": "T20",
"gender": "male",
"team_type": "club",
"balls_per_over": 6,
"overs_limit": 20,
"venue": {
"id": "venue_cs_narendra-modi-stadium-ahmedabad",
"name": "Narendra Modi Stadium",
"city": "Ahmedabad"
},
"teams": [
{
"id": "team_cs_gujarat-titans",
"name": "Gujarat Titans"
},
{
"id": "team_cs_royal-challengers-bengaluru",
"name": "Royal Challengers Bengaluru"
}
],
"toss": {
"team_id": "team_cs_royal-challengers-bengaluru",
"team": "Royal Challengers Bengaluru",
"decision": "field"
},
"result": "Royal Challengers Bengaluru won by 5 wickets",
"winner_id": "team_cs_royal-challengers-bengaluru",
"outcome": {
"by": {
"wickets": 5
},
"method": null
},
"player_of_match": [
{
"id": "player_cs_ba607b88",
"name": "V Kohli"
}
],
"innings": [
{
"number": 1,
"team_id": "team_cs_gujarat-titans",
"team": "Gujarat Titans",
"super_over": false,
"declared": false,
"forfeited": false,
"target": null,
"total": {
"runs": 155,
"wickets": 8,
"overs": "20",
"balls": 120
}
},
{
"number": 2,
"team_id": "team_cs_royal-challengers-bengaluru",
"team": "Royal Challengers Bengaluru",
"super_over": false,
"declared": false,
"forfeited": false,
"target": {
"overs": 20,
"runs": 156
},
"total": {
"runs": 161,
"wickets": 5,
"overs": "18",
"balls": 108
}
}
],
"source": {
"name": "Cricsheet",
"id": "1535465",
"url": "https://cricsheet.org/matches/1535465",
"licence": "ODC-By 1.0"
}
},
"meta": {
"source": "Cricsheet",
"source_url": "https://cricsheet.org",
"licence": "ODC-By 1.0",
"licence_url": "https://opendatacommons.org/licenses/by/1-0/",
"additional_source": "ESPN, for domestic and youth competitions Cricsheet does not cover"
}
}Bearer API keys
Every endpoint requires a key. A free Starter key covers matches, scorecards and season tables from the last 12 months, plus competitions, teams, players and search, with 1,000 requests a month and 10 a minute. A Developer key adds the full archive, live scores, fixtures, deliveries, overs, partnerships, phase splits, matchups, fantasy points and venue profiles, with 250,000 requests a month. Raw keys start with oc_live_. OpenCricketAPI stores only a hash.
Authorization: Bearer oc_live_your_api_keyWhat is actually available
Cricsheet · ODC-By 1.0Ball-by-ball history
Men's and women's Tests, ODIs, T20Is, ICC events and the major T20 leagues since 2001, refreshed as new matches are published. Some domestic and youth competitions Cricsheet does not cover come from ESPN, and are labelled so.
Computed from deliveriesOvers, partnerships, phases, matchups, fantasy points
Calculated from the delivery and scorecard records. Nothing is estimated, and nothing is added that the records do not contain. Fantasy points return their full rules and every player's event counts.
ESPN · no open licenceLive scores and fixtures
Matches in progress, the live match centre and fixtures for up to 14 days, from ESPN's public scoreboard, refreshed about every 20 seconds and labelled ESPN. Fine for score apps and dashboards, not for in-play betting.
No sourceShot direction and pitch maps
Open data does not record where the ball went or pitched, so there are no wagon wheels or beehives.
Every response includes source and licence metadata. See coverage for the full catalog.
19 endpoints
/v1/competitionsLeagues, ICC events and domestic competitions with seasons and match counts.
Starter plan · format, gender, group
/v1/competitions/{id}/standingsPoints table for a season's league stage: played, won, lost, no result, net run rate and points.
Starter plan · season
/v1/competitions/{id}/leadersSeason leaderboards: most runs and wickets, sixes, highest scores, best figures, strike rate and economy.
Starter plan · season, category
/v1/matchesFind matches by competition, season, team, venue, format or date range.
Starter plan · competition, season, team, venue, format, gender, from, to, limit, cursor
/v1/matches/{id}Match summary: teams, toss, result, venue, officials and innings totals.
Starter plan
/v1/matches/{id}/scorecardFull batting and bowling scorecard with dismissals and fall of wickets.
Starter plan · innings
/v1/matches/{id}/deliveriesEvery ball: batter, bowler, runs, extras, wickets and fielders.
Developer plan · innings, over_from, over_to, cursor
/v1/matches/{id}/oversOver-by-over runs and wickets for Manhattan and worm charts.
Developer plan · innings
/v1/matches/{id}/partnershipsPartnership runs and balls for every wicket.
Developer plan · innings
/v1/matches/{id}/phasesPowerplay, middle and death-over splits for limited-overs innings: the recorded powerplay where the source has it, fixed over ranges otherwise, each labelled.
Developer plan · innings
/v1/matches/{id}/fantasy-pointsFantasy points for every player in a match, counted from the scorecard, with the full rules and each player's event counts so you can apply your own scoring.
Developer plan · ruleset
/v1/teams/{id}Team profile with recent matches and competitions.
Starter plan
/v1/players/{id}Player profile with Cricsheet registry ID and career splits by format.
Starter plan
/v1/players/{id}/matchupsBatter-versus-bowler history: balls, runs, dismissals, strike rate.
Developer plan · role, opponent, format, limit
/v1/venues/{id}Venue profile: matches hosted, average first-innings score, toss decisions.
Developer plan
/v1/liveMatches in progress worldwide with live scores and status, refreshed about every 20 seconds.
Developer plan · state, competition
/v1/live/{id}Live match centre: innings totals, the batters and bowlers in the middle, and the last 18 balls.
Developer plan
/v1/fixturesUpcoming matches for up to 14 days: start time, teams, venue and competition.
Developer plan · from, to, competition
/v1/searchSearch players, teams, competitions and venues by name.
Starter plan · q, type, limit
Filter matches without learning source IDs
Filters can be combined. Dates are UTC calendar dates. Entity filters use the stable IDs returned by search.
| Parameter | Type | Description |
|---|---|---|
competition | string | Competition ID, e.g. comp_indian-premier-league. |
season | string | Season label, e.g. 2026 or 2025/26. |
team | string | Team ID, e.g. team_cs_india. |
venue | string | Venue ID, e.g. venue_cs_eden-gardens-kolkata. |
format | enum | Match format. One of: Test, ODI, T20, T10, One-day, Multi-day. |
gender | enum | Men's (male) or women's (female) cricket. One of: male, female. |
from | date | Matches on or after this date. |
to | date | Matches on or before this date. |
limit | integer | Matches per page, newest first. 1-100, default 50. |
cursor | string | meta.next_cursor from the previous page. |
Use the same endpoint from any stack
const res = await fetch(
"https://opencricketapi.com/v1/matches/match_cs_1535465/scorecard",
{ headers: { Authorization: `Bearer ${process.env.OPENCRICKET_KEY}` } }
);
if (!res.ok) throw new Error((await res.json()).error.code);
const { data, meta } = await res.json();
console.log(data[1].total, meta.licence);import os, requests
res = requests.get(
"https://opencricketapi.com/v1/matches/match_cs_1535465/overs",
headers={"Authorization": f"Bearer {os.environ['OPENCRICKET_KEY']}"},
timeout=10,
)
res.raise_for_status()
for over in res.json()["data"][1]["overs"]:
print(over["over"], over["runs"], over["wickets"])One envelope across every endpoint
Successful requests return data and meta. Failed requests return error and a request ID.
dataThe requested resourceAn object or array with normalized field types.metaHow the response was producedSource, licence, count and pagination cursor.errorA stable failure shapeMachine-readable code plus a human-readable message.200Request completed400Invalid filters401Invalid API key403Plan restriction404Resource missing429Quota exhaustedBall-by-ball deliveries
One record per ball, including wides and no-balls. Ball codes are a compact summary. Every delivery also carries the full objects below.
batter / bowlerPlayer IDs and namesrunsBatter, extras and totalextrasWides, no-balls, byes, leg byeswicketsKind, player out and fieldersover / ballPosition in the inningscodeCompact summary: 0, 4, 6, W, 1wd{
"data": [
{
"over": 18,
"ball": 1,
"legal_ball": 1,
"batter_id": "player_cs_800d2d97",
"bowler_id": "player_cs_12314277",
"non_striker_id": "player_cs_ba607b88",
"runs": {
"batter": 1,
"extras": 0,
"total": 1
},
"code": "1"
},
{
"over": 18,
"ball": 2,
"legal_ball": 2,
"batter_id": "player_cs_ba607b88",
"bowler_id": "player_cs_12314277",
"non_striker_id": "player_cs_800d2d97",
"runs": {
"batter": 1,
"extras": 0,
"total": 1
},
"code": "1"
}
],
"meta": {
"source": "Cricsheet",
"source_url": "https://cricsheet.org",
"licence": "ODC-By 1.0",
"licence_url": "https://opendatacommons.org/licenses/by/1-0/",
"additional_source": "ESPN, for domestic and youth competitions Cricsheet does not cover",
"match_id": "match_cs_1535465",
"innings": 2,
"team_id": "team_cs_royal-challengers-bengaluru",
"count": 6,
"total": 6,
"next_cursor": null
}
}Typed, predictable errors
Errors use stable codes, including invalid_api_key, monthly_quota_exceeded, plan_restriction, match_not_found and feature_not_available. feature_not_available means the source does not publish that data for this match.
{ "error": { "code": "plan_restriction", "message": "Deliveries need a Developer key." } }