Volleyball API
DocumentationLiveCoveragePricingMCPStatusSign inGet a free key

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.

PlansFree keyLiveArchiveComplete
Base URLhttps://api.volleyballapi.com
Answerone object

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.

NameTypeWhat it doesExample
idpathThe 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"

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.

200 application/json
{
  "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

FieldTypeWhat it holds
idstringStable match id, mt_
disciplineenumindoor or beach
genderenummen, women or mixed
statusenumscheduled, live, finished, awarded or cancelled
current_setintThe set being played, while live; otherwise null
date, time_localdate, timeThe venue's calendar day and clock
start_utcdatetimeScheduled start in UTC, ISO 8601
competitionobjectid, name and season
round, poolstring"Semifinals", "Pool B", or null
team_a, team_bobjectid and name: a club, a national team or a beach pair
scoreobjectSets won by each side
winnerenuma or b, null until finished
setsarrayEach set: number, points each side, duration in seconds
sets_completeboolfalse when the source's set scores do not add up to its result, so some sets are missing
duration_sintMatch length in seconds
updated_utcdatetimeWhen anything in the match last changed
venue, city, country_codestringWhere it was played
spectatorsintOfficial attendance
refereesarrayFirst and second referee
coachesobjectteam_a and team_b: each head coach, or null
weatherobjectBeach 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
detailobjectLinks 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.

HTTPCodeWhen
401unauthorizedNo key, or a key that is not known or was revoked
403upgrade_requiredA day outside your plan: the free key reads today and yesterday, Live the last 30 days
404not_foundAn id that does not exist
422unknown_parameterA parameter this endpoint does not take; the answer lists the ones it does
429rate_limitedToo many calls this minute; Retry-After says when to try again
429quota_exceededThe 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.