--- name: cricketdatabase description: Look up cricket results, scorecards, every ball, live scores, player careers, head-to-heads and records with the Cricket Database API or its MCP server. Use when a question needs real cricket data (internationals, franchise leagues and domestic cricket, men and women, every ball since 2001, international results back to 1877) rather than memory. --- # Cricket Database Cricket Database (cricketdatabase.com) holds every ball of international, franchise and domestic cricket since December 2001, men and women, and the result of every international back to 1877. The API answers JSON at `https://api.cricketdatabase.com/v1`; the MCP server at `https://api.cricketdatabase.com/mcp` gives the same data as tools. ## When to use it - Use it for results, scorecards, ball-by-ball data, live scores, careers, head-to-heads, competition seasons, records and analytics (splits, phases, batter against bowler). - Do not use it for news, injuries, team selection, fixtures far ahead or betting odds: it does not hold them. - Prefer a call over memory for any figure: totals and careers change after every match. ## Getting access - A free key takes one step with Google, no card: https://cricketdatabase.com/account/sign-in - Keys start `cdb_live_`. Send the key as `Authorization: Bearer ` or `X-API-Key: `. Never put it in the address: a `?key=` answers 400. - `GET /v1` (the list of endpoints) and `GET /v1/status` need no key. - `GET /v1/usage` shows the key's plan, limits and what is left today, and never counts against the quota. ## The calls for common questions Every answer is `{"data": ..., "meta": ...}`. Things that point elsewhere carry their address (a slug), so you can follow them with the next call. Find the address of a player, team, ground or competition by name: ``` curl -H "Authorization: Bearer $CDB_KEY" "https://api.cricketdatabase.com/v1/search?q=root" {"data": {"q": "root", "players": [{"player": "je-root", "name": "JE Root", "matches": 507}, ...], "teams": [...], "venues": [...], "competitions": [...]}, "meta": {...}} ``` Results from the latest day: ``` curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/results/yesterday {"data": [{"match": "2026-10-03-india-v-west-indies", "format": "Test", "teams": [...], "result": "..."}], "meta": {...}} ``` Matches for a day or with filters (`date`, `from`, `to`, `year`, `month`, `format`, `gender`, `team`, `venue`, `competition`, `coverage`), then one match: ``` curl -H "Authorization: Bearer $CDB_KEY" "https://api.cricketdatabase.com/v1/matches?date=2026-10-03" curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/matches/{slug}/scorecard curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/matches/{slug}/deliveries ``` Every match carries `coverage`: `full` (every ball), `scorecard` (an older international with every batter's and bowler's line as the scorer kept it, answered by `/v1/matches/{slug}/scorecard` with `balls_per_over`; balls faced can be null and the card does not name the fielder or bowler for each dismissal), `totals` (an older international with its innings totals, extras and fall of wickets, answered by `/v1/matches/{slug}` under `innings`) or `result_only`. The scorecard also has `weather`: each match day's highest and lowest temperature, rain, humidity, dew point and wind at the ground. A player's career by format, and every innings: ``` curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/players/je-root/stats curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/players/je-root/innings ``` Two teams against each other, and a record list: ``` curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/teams/england/head-to-head/australia curl -H "Authorization: Bearer $CDB_KEY" "https://api.cricketdatabase.com/v1/records?type=most-runs&format=test&gender=male" ``` Live scores (Match Week, Pro and Analyst Pro): ``` curl -H "Authorization: Bearer $CDB_KEY" "https://api.cricketdatabase.com/v1/live?international=true" curl -H "Authorization: Bearer $CDB_KEY" https://api.cricketdatabase.com/v1/live/{slug} ``` Every endpoint, with its parameters and an example answer, is documented at https://cricketdatabase.com/documentation, and as OpenAPI at https://cricketdatabase.com/openapi.json. ## MCP server - Address: `https://api.cricketdatabase.com/mcp` (streamable HTTP), with the key as `Authorization: Bearer `. - Tools: `find`, `search_matches`, `latest_results`, `live_scores`, `live_match`, `get_match`, `get_scorecard`, `get_deliveries`, `get_partnerships`, `player_career`, `player_innings`, `head_to_head`, `competition`, `top_performances`, `batter_vs_bowler`, `player_splits`. - Each tool is one API call on the caller's key, so it answers exactly what the plan answers. At most 10 messages in one batch. ## Limits | Plan | Calls a minute | Calls a day | |---|---|---| | Free key | 10 | 50 | | Match Week | 60 | 5,000 | | Archive | 120 | 25,000 | | Pro | 180 | 50,000 | | Analyst Pro | 300 | 100,000 | - The free key has the last 30 days in full, and samples of older matches. - Match Week has the last 7 days and live scores; Archive has every match up to yesterday; Pro has both; Analyst Pro adds the analytics endpoints. - The minute resets on the minute, the day at midnight UTC. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset` and `X-Plan`: read them rather than counting. - Only successful calls count against the day. All times are UTC. ## Errors Every error has one shape; decide from `code`, which never changes: ``` {"error": {"code": "upgrade_required", "message": "...", "plan": "archive", "docs": "https://cricketdatabase.com/documentation/guides/errors"}} ``` | Status | Code | What to do | |---|---|---| | 400 | bad_request | Fix the value named in the message | | 401 | unauthorized | Send a current key | | 403 | upgrade_required | `plan` names the plan that opens it | | 404 | not_found | Check the address; `/v1/search` finds the right one | | 404 | no_ball_by_ball | The match has a scorecard but no balls (coverage `scorecard`); ask for its scorecard | | 404 | no_scorecard | The match has no scorecard (coverage `totals` or `result_only`); ask for the match itself | | 422 | unknown_parameter | Drop the parameter named; `allowed` lists the ones taken | | 429 | rate_limited | Wait for `Retry-After` (a few seconds) | | 429 | quota_exceeded | The day is used; wait for midnight UTC | | 500 | server_error | Try again later | ## A typical workflow 1. Turn names into addresses with `/v1/search?q=` (or the `find` tool). 2. Ask the narrowest endpoint that answers the question: a scorecard for one match, `/stats` for a career, `/head-to-head` for two sides. 3. Follow the slugs in the answer for more detail, one call at a time. 4. On 403, tell the user which plan opens it rather than guessing the figure. 5. On 429 `rate_limited`, wait for `Retry-After` and try again; on `quota_exceeded`, stop for the day. 6. Quote figures as the API gives them, with the match or player address so the user can check them on cricketdatabase.com.