Documentation

18 cricket data endpoints over REST and MCP. One key, credits per call.

Coming from CricketData.org, Sportmonks or EntitySport? See how they compare.

Your first call

Sign up for a free key (500 credits every month, no card), swap it in for YOUR_API_KEY, and send this. search_players costs 1 credit.

Request

curl -X POST https://mcp.yorkerapi.com/v1/search_players \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
  "name": "kohli"
}'

Response

json

{
  "players": [
    {
      "player_id": "ba607b88",
      "name": "V Kohli",
      "full_name": "Virat Kohli",
      "matches": 837,
      "last_match": "2026-10-03",
      "last_team": "India"
    },
    {
      "player_id": "eb9082b2",
      "name": "A Kohli",
      "full_name": null,
  ...

First 14 lines. Full response and every field

REST / cURL

POST to /v1/{tool_name} with your params as JSON body. No MCP client needed:

bash

curl -X POST https://mcp.yorkerapi.com/v1/get_schedule \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY"

With parameters:

bash

curl -X POST https://mcp.yorkerapi.com/v1/search_players \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"name":"kohli"}'

Save the raw JSON

Keep your key in an environment variable so it never sits in a script or a chat, and write each response to a file:

bash

export YORKERAPI_API_KEY="your key here"

curl -s -X POST https://mcp.yorkerapi.com/v1/search_players \
  -H "Content-Type: application/json" \
  -H "x-api-key: $YORKERAPI_API_KEY" \
  -d '{"name":"kohli"}' \
  -o search_players.json

The file holds exactly what the API returned. Tools that page their results return a next_offset; send it back as offset for the next page.

ChatGPT and Claude

Both connect to the MCP server with a sign-in instead of a key: you sign in to YorkerAPI once and press Allow. Step-by-step for ChatGPT and Claude.

Claude Desktop

Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "yorkerapi": {
      "url": "https://mcp.yorkerapi.com/mcp?key=YOUR_API_KEY"
    }
  }
}

Claude Code

One command:

bash

claude mcp add yorkerapi https://mcp.yorkerapi.com/mcp?key=YOUR_API_KEY --transport streamable-http

Find the right call

All 18 questions

What timestamps mean, whether lines are pre-game, and what you can do with the data: data timing and rights.

Guides

All guides

Working Python, JavaScript and cURL for common questions, each run against the live API.

Endpoints

18 endpoints by category. Each page has parameters, requests in three formats, a full example response and every response field.

Static reference1 credit/call

Basic lookup2 credits/call

Stats + aggregation5 credits/call

Multi-table5 credits/call

Time-series10 credits/call

Reference

Authentication

Every request requires an API key. Pass it via header or query parameter:

bash

x-api-key: YOUR_API_KEY
# or
Authorization: Bearer YOUR_API_KEY
# or (MCP only)
?key=YOUR_API_KEY

Verify your email, then create an API key from the dashboard. Free accounts get 500 credits every month.

Base URL

text

https://mcp.yorkerapi.com

REST API: POST /v1/{tool} with JSON body. Works with cURL, Python, any HTTP client.

MCP: POST /mcp via Streamable HTTP. Works with Claude Desktop, Claude Code, Cursor, and any MCP client.

Rate limits

Credit balance	Rate limit
100 credits or more	60 req/min
Under 100 credits	10 req/min

The limit is the same on every plan. It is burst protection, not the spend boundary; credits are that, and they are enforced per request. Running low slows you down so you notice before the balance reaches zero.

Error handling

Code	Meaning	What to do
400	Invalid parameters	Check required fields and value types
401	Invalid or missing API key	Check your x-api-key header
402	Insufficient credits	Top up your wallet or upgrade your plan
429	Rate limit exceeded	Wait and retry (see limits above)
500	Server error	Retry with idempotency key. Credits auto-refund on server errors.

Pass x-idempotency-key or x-request-id headers to make retries duplicate-safe.

Data coverage

Test cricket (Tests)

YorkerAPI also serves the Tests. Pass "league": "test" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/test. Tests API coverage.

One Day Internationals (ODIs)

YorkerAPI also serves the ODIs. Pass "league": "odi" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/odi. ODIs API coverage.

Twenty20 Internationals (T20Is)

YorkerAPI also serves the T20Is. Pass "league": "t20i" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/t20i. T20Is API coverage.

Indian Premier League (IPL)

YorkerAPI also serves the IPL. Pass "league": "ipl" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/ipl. IPL API coverage.

Big Bash League (BBL)

YorkerAPI also serves the BBL. Pass "league": "bbl" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/bbl. BBL API coverage.

Pakistan Super League (PSL)

YorkerAPI also serves the PSL. Pass "league": "psl" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/psl. PSL API coverage.

Caribbean Premier League (CPL)

YorkerAPI also serves the CPL. Pass "league": "cpl" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/cpl. CPL API coverage.

T20 Blast (English county Twenty20) (T20 Blast)

YorkerAPI also serves the T20 Blast. Pass "league": "blast" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/blast. T20 Blast API coverage.

The Hundred (men) (The Hundred)

YorkerAPI also serves The Hundred. Pass "league": "hundred" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/hundred. The Hundred API coverage.

SA20 (South Africa) (SA20)

YorkerAPI also serves the SA20. Pass "league": "sa20" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/sa20. SA20 API coverage.

International League T20 (UAE) (ILT20)

YorkerAPI also serves the ILT20. Pass "league": "ilt20" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/ilt20. ILT20 API coverage.

County Championship (English first-class) (County Championship)

YorkerAPI also serves the County Championship. Pass "league": "county" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/county. County Championship API coverage.

Women's Big Bash League (WBBL)

YorkerAPI also serves the WBBL. Pass "league": "wbbl" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/wbbl. WBBL API coverage.

Women's Premier League (India) (WPL)

YorkerAPI also serves the WPL. Pass "league": "wpl" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/wpl. WPL API coverage.

The Hundred (women) (The Hundred (women))

YorkerAPI also serves The Hundred (women). Pass "league": "hundred_women" to any tool that lists it, or connect to https://mcp.yorkerapi.com/mcp/hundred_women. The Hundred (women) API coverage.

Data	Status	Coverage	Volume
Matches and scorecards Teams, venue, toss, result and margin, innings totals, the playing sides and the player of the match, for every format and competition. get_matches get_match Updated within a day of a match ending. Not a live feed.	Partial	2001 to current	23,241 matches
Ball by ball Every ball, legal or not: over and ball, batter, non-striker, bowler, runs off the bat and extras, the kind of extra, and any wicket with the fielders involved. get_deliveries No ball length, line, speed or shot direction.	Partial	2001 to current	11.7 million deliveries
Players A player is one person across Tests, ODIs, T20Is and every domestic competition, men's and women's. search_players get_player get_matchup No date of birth, batting hand or bowling style.	Partial	Everyone in a listed match	One id across every format and competition
Match-winner prices Each sportsbook's price on each side, opening and closing, for the internationals and the major franchise and county competitions. get_odds get_line_movement Match winner only: no spreads, totals or player props. Prices cover Tests, ODIs, T20Is, the IPL, BBL, PSL, CPL, T20 Blast and The Hundred; other competitions have none.	Partial	June 2020 to current	About 93% of priced matches linked to ball-by-ball
In-play prices Match-winner prices taken after the first ball, kept apart from the pregame lines. get_line_movement Tied to the match clock, not to a ball.	Partial	June 2020 to current	Snapshots by sportsbook
Team ratings Our Elo for international sides and franchises, before and after every match, from results alone. get_ratings get_match Ratings are ours, not an official ranking. New sides start level, so a side with few matches has a rating that means little.	Partial	2001 to current	One Elo per team and format
Win probability Our model's chance the batting side wins after each ball, from the score against par, wickets, balls left, the target and the two sides' ratings. get_win_probability get_deliveries Not for Tests or first-class matches. It is a model, tested on matches it was not fitted on, and the closing market beats our pre-match ratings.	Partial	Limited overs, 2002 to current	Every ball of about 20,000 matches

Coverage describes the datasets YorkerAPI supports. Freshness and operational health are tracked separately.

Odds snapshot definitions

opening: The first match-winner price a sportsbook posted for the match.

closing: The sportsbook's last match-winner price before the first ball.

Odds coverage currently documents match-winner prices from mid-2020. Match-winner only, for the internationals and the major franchise and county competitions. A median of 29 books on IPL closing lines, 29 on The Hundred, 25 on the T20 Blast, 23 on T20Is, 22 on Tests, 18 on the BBL and 17 on ODIs; 14 in 2020, 29 in 2026. Cricket prices are match-winner only, by sportsbook, from mid-2020. Prices taken after the first ball are kept apart from the pregame lines and are never served as one.

Response format

REST API

All successful REST responses wrap the result in a data key:

json

{ "data": { "matches": [...], "count": 50 } }

Error responses return:

json

{ "error": "Insufficient credits", "message": "This tool costs 5 credits, you have 2" }

MCP Protocol

MCP responses follow the standard MCP tool result format. The data is returned directly (no data wrapper). Both access methods return identical data, just different envelopes.

Conventions

Seasons: the season string a competition uses: a year (2025) or the two-year span of a winter series (2024/25). Example: 2024/25.

Match IDs: A match's id is a number, e.g. 1422119. Find one by listing matches.

Team IDs: A slug of the side's name: india, india-women, mumbai-indians.

Player IDs: Eight hex characters. One id follows a player through every format and competition.

Competitions: Pass competition to narrow a call to one competition: test, odi, t20i, ipl, bbl, psl, cpl, blast, hundred, sa20, ilt20, county, wbbl, wpl or hundred_women.

Pagination: Endpoints use a limit parameter. No cursor or offset. Narrow your filters to get different slices of data.

Credits: Deducted before the request executes. Automatically refunded on server errors. Monthly credits are used first, then wallet balance.

Ready to start?

500 free credits every month. No credit card required.

Get a free key