DocumentationMatches
Volleyball match API
GET/v1/matches/{id}
One match in full: both teams, the result, every set with its duration, the venue, city and country, attendance and referees, and links to its rallies and player figures when they exist.
Parameters
Days you can read depend on your plan: the free key reads today and yesterday, Live the last 30 days, Archive and Complete every season since 2001.
| Name | Type | What it does | Example |
|---|---|---|---|
id | path | The match id, in the address. Required. | mt_zzy8fh10 |
Request
Send your key in the Authorization header as a Bearer token, or in X-API-Key. A key in the address is refused, so it never ends up in a log.
# One match: teams, result, every set, duration, venue, spectators and referees curl "https://api.volleyballapi.com/v1/matches/mt_zzy8fh10" \ -H "Authorization: Bearer $VBA_KEY"
$ch = curl_init('https://api.volleyballapi.com/v1/matches/mt_zzy8fh10'); curl_setopt_array($ch, [ CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('VBA_KEY')], CURLOPT_RETURNTRANSFER => true, ]); $res = json_decode(curl_exec($ch), true); print_r($res['data']);
import os, requests r = requests.get( "https://api.volleyballapi.com/v1/matches/mt_zzy8fh10", headers={"Authorization": f"Bearer {os.environ['VBA_KEY']}"}, ) print(r.json()["data"])
const res = await fetch("https://api.volleyballapi.com/v1/matches/mt_zzy8fh10", { headers: { "X-API-Key": process.env.VBA_KEY }, }); const { data, meta } = await res.json();
Response
Every answer is data plus meta. This is a real answer to the request above, counted 2026-10-12, with long lists cut short.
{
"data": {
"id": "mt_zzy8fh10",
"discipline": "indoor",
"gender": "women",
"status": "finished",
"current_set": null,
"date": "2023-08-30",
"time_local": "15:00",
"start_utc": "2023-08-30T08:00:00Z",
"competition": {
"id": "cp_tayx7he8",
"name": "Women's Asian Senior Championship 2023",
"season": 2023
},
"round": null,
"pool": "Pool C",
"team_a": { "id": "tm_rk2hqqay", "name": "Korea" },
"team_b": { "id": "tm_tzqa4pxd", "name": "Vietnam" },
"score": { "a": 2, "b": 3 },
"winner": "b",
"sets": [
{ "set": 1, "a": 25, "b": 22, "duration_s": 1620 },
{ "set": 2, "a": 25, "b": 19, "duration_s": 1740 },
{ "set": 3, "a": 23, "b": 25, "duration_s": 1680 },
{ "set": 4, "a": 17, "b": 25, "duration_s": 1500 },
...
],
"sets_complete": true,
"duration_s": 7620,
"updated_utc": "2026-09-29T12:34:50Z",
"venue": "Nakhon Ratchasima",
"city": "Nakhon Ratchasima",
"country_code": "TH",
"spectators": 1000,
"referees": [],
"coaches": { "team_a": null, "team_b": null },
"detail": {
"points": "https://api.volleyballapi.com/v1/matches/mt_zzy8fh10/points",
"players": null,
"lineups": null
}
},
"meta": { "plan": "Complete" }
}Fields
| Field | Type | What it holds |
|---|---|---|
id | string | Stable match id, mt_ |
discipline | enum | indoor or beach |
gender | enum | men, women or mixed |
status | enum | scheduled, live, finished, awarded or cancelled |
current_set | int | The set being played, while live; otherwise null |
date, time_local | date, time | The venue's calendar day and clock |
start_utc | datetime | Scheduled start in UTC, ISO 8601 |
competition | object | id, name and season |
round, pool | string | "Semifinals", "Pool B", or null |
team_a, team_b | object | id and name: a club, a national team or a beach pair |
score | object | Sets won by each side |
winner | enum | a or b, null until finished |
sets | array | Each set: number, points each side, duration in seconds |
sets_complete | bool | false when the source's set scores do not add up to its result, so some sets are missing |
duration_s | int | Match length in seconds |
updated_utc | datetime | When anything in the match last changed |
venue, city, country_code | string | Where it was played |
spectators | int | Official attendance |
referees | array | First and second referee |
coaches | object | team_a and team_b: each head coach, or null |
weather | object | Beach matches only: at_start (temp_c, humidity_pct, wind_ms, rain_mm in the hour the match started) and day (temp_min_c, temp_max_c, wind_max_ms, rain_mm over its day, UTC); null until the tournament's weather is read, a few days after it ends |
detail | object | Links to the rallies, player figures and lineups, or null when there are none |
Errors
Errors come back as {"error": {"code", "message", "docs"}}, with plan and pricing added when a plan would answer. Every error.
| HTTP | Code | When |
|---|---|---|
| 401 | unauthorized | No key, or a key that is not known or was revoked |
| 403 | upgrade_required | A day outside your plan: the free key reads today and yesterday, Live the last 30 days |
| 404 | not_found | An id that does not exist |
| 422 | unknown_parameter | A parameter this endpoint does not take; the answer lists the ones it does |
| 429 | rate_limited | Too many calls this minute; Retry-After says when to try again |
| 429 | quota_exceeded | The day's or month's allowance is used; the answer says when it resets |
Try it
Fill in what you need; the request is built as you type. Paste your key to run it here, straight against the API.