--- name: volleyballapi description: Look up indoor and beach volleyball live scores, results with every set, rally-by-rally points, lineups, player figures, competitions, standings, teams and head-to-head records through the Volleyball API. Use when a user asks about volleyball matches, scores, teams or players, or wants volleyball data in an app. --- # Volleyball API Volleyball data as JSON over HTTPS: live scores, results with every set, rally-by-rally points, lineups and player figures for indoor and beach volleyball, from world championships and tours to national leagues. Operated by DeveloperData.net. All times are UTC. ## When to use it - Use it for factual volleyball questions: who won, the set scores, what is live now, a team's recent matches, a player's profile, two teams' record against each other. - Use it to build apps, sites and dashboards that show volleyball data. - Do not use it for predictions, tips or betting advice: it holds factual data only. - Other sports are not covered. ## Getting access 1. Sign in with Google at https://volleyballapi.com/signup. A free key is made at once and shown once on the account page. Keys start with `vba_`. 2. Send the key in a header on every call, either `Authorization: Bearer ` or `X-API-Key: `. A key in the address (`?key=`) is refused. 3. Base URL: `https://api.volleyballapi.com/v1`. Ask the user for their key; never invent one. The free key reads today's and yesterday's matches, competitions, teams and players. Paid plans add history, live scores, rallies and player figures: https://volleyballapi.com/pricing ## The calls that answer common questions Every answer is `{"data": ..., "meta": {...}}`. Ids are stable strings: `mt_` matches, `cp_` competitions, `tm_` teams, `pl_` players. Responses below are trimmed. What finished yesterday: ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/results/yesterday?discipline=indoor&per_page=2" ``` ```json {"data": [{"id": "mt_...", "discipline": "indoor", "gender": "women", "status": "finished", "date": "2026-10-09", "competition": {"id": "cp_...", "name": "...", "season": 2026}, "team_a": {"id": "tm_...", "name": "..."}, "team_b": {"id": "tm_...", "name": "..."}, "score": {"a": 3, "b": 1}, "winner": "a", "sets": [{"set": 1, "a": 25, "b": 21, "duration_s": 1560}]}], "meta": {"plan": "Free key", "count": 2, "next_cursor": "..."}} ``` What is being played now (Live and Complete plans): ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/matches/live" ``` Matches on a day or between two days, with filters (`date`, `from`, `to`, `discipline`, `gender`, `status`, `competition`, `team`): ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/matches?date=2026-10-09&discipline=beach" ``` One match in full (venue, spectators, referees, coaches, weather for beach): ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/matches/mt_..." ``` Find a team, then its matches: ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/teams?q=brazil&gender=women" curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/teams/tm_.../matches" ``` Find a player, then their profile: ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/players?q=smith" curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/players/pl_..." ``` The player answer carries `career`: one entry per competition and team, newest first, with season, matches, won, and points, kills, aces and blocks where the match sheets have them. Two teams' record against each other: ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/head-to-head?team_a=tm_...&team_b=tm_..." ``` ```json {"data": {"team_a": {"id": "tm_...", "name": "..."}, "team_b": {"id": "tm_...", "name": "..."}, "record": {"team_a_won": 7, "team_b_won": 4, "meetings": 11}, "matches": [...]}} ``` Rallies, player figures and lineups for one match (paid plans): `/v1/matches/{id}/points`, `/v1/matches/{id}/players`, `/v1/matches/{id}/lineups`. Competitions: `/v1/competitions?discipline=beach&season=2026`, then `/v1/competitions/{id}/matches`. League table or pool standings, worked out from the results (every plan): ``` curl -H "Authorization: Bearer $VBA_KEY" "https://api.volleyballapi.com/v1/competitions/cp_.../standings" ``` ```json {"data": {"competition": {"id": "cp_...", "name": "..."}, "tables": [{"stage": null, "pool": null, "rows": [ {"rank": 1, "team": {"id": "tm_...", "name": "..."}, "played": 22, "won": 19, "lost": 3, "points": 56, "sets_won": 61, "sets_lost": 18, "set_ratio": 3.389, "points_won": 1902, "points_lost": 1611, "point_ratio": 1.181, "form": "WWWLW"}]}]}, "meta": {"matches": 132, "pending": 0, "tables": 1}} ``` Indoor: 3 points for a 3-0 or 3-1 win, 2 for 3-2, 1 for a 2-3 loss. Beach pools: 2 for a win, 1 for a loss. One table per stage and pool. Knockout rounds are left out; add `stage=all` to count them, `pool=B` for one pool or stage. Your plan and what is left: `/v1/usage` (never counted). The full list of endpoints, with every parameter and field: https://volleyballapi.com/documentation and, in one file, https://volleyballapi.com/documentation/manual.md ## MCP server `https://api.volleyballapi.com/mcp`, MCP over HTTP (JSON-RPC by POST), with the same key in `Authorization: Bearer`. Every endpoint is a tool named after its documentation page, for example `results_yesterday`, `live`, `matches`, `match`, `match_points`, `match_players`, `match_lineups`, `competitions`, `competition_standings`, `teams`, `team_matches`, `players`, `player`, `head_to_head`, `usage`. Listing the tools needs no key. Guide: https://volleyballapi.com/documentation/mcp ## Limits - Free key: 50 calls a day, 10 a minute, today and yesterday only, no live scores, rallies or player figures. - Live: 50,000 calls a month, 60 a minute, the last 30 days, live scores and rallies. - Archive: 50,000 calls a month, 60 a minute, every season, rallies and player figures, no live scores. - Complete: 250,000 calls a month, 120 a minute, everything, plus bulk export (`/v1/export/matches`, `/v1/export/lineups`, `/v1/export/points` with `from` and `to`). - Lists answer 50 rows a page, up to 200 with `per_page`; follow `meta.next_cursor` with `cursor` for long pulls. - Every answer carries `X-RateLimit-Remaining` and `X-Quota-Remaining`. ## Errors `{"error": {"code": "...", "message": "...", "docs": "https://volleyballapi.com/documentation/..."}}` | HTTP | code | Meaning | |---|---|---| | 400 | bad_request | A value of the wrong shape, or a key sent in the address | | 401 | unauthorized | No key, or an unknown or revoked key | | 403 | upgrade_required | The plan does not include this endpoint or day; `plan` names one that does | | 404 | not_found | No such endpoint or id | | 422 | unknown_parameter | A parameter the endpoint does not take | | 429 | rate_limited | Too many calls this minute; wait `Retry-After` seconds | | 429 | quota_exceeded | The day's or month's calls are used; the answer says when it resets | ## A typical workflow 1. Call `/v1/usage` to learn the plan and what it reads. 2. Turn names into ids with `/v1/teams?q=`, `/v1/players?q=` or `/v1/competitions?q=`. 3. Ask for matches by day (`/v1/matches?date=`), by team or by competition. 4. Open one match with `/v1/matches/{id}` and, on a paid plan, its points, players or lineups. 5. On a 403, tell the user which plan would answer; on a 429, wait and try again, or stop.