DocumentationCompetitions
Volleyball team rosters by competition API
GET/v1/competitions/{id}/rosters
The players each team registered for a competition, team by team in shirt order: shirt number, captain, libero, position where given, nationality, birth date and height. International indoor competitions from 2018 on, read from the official registrations, so a squad is there before its first match.
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 competition id, in the address. Required. | cp_kxgcx249 |
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.
# The players each team registered for a competition: shirt, captain, libero, birth date and height curl "https://api.volleyballapi.com/v1/competitions/cp_kxgcx249/rosters" \ -H "Authorization: Bearer $VBA_KEY"
$ch = curl_init('https://api.volleyballapi.com/v1/competitions/cp_kxgcx249/rosters'); 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/competitions/cp_kxgcx249/rosters", headers={"Authorization": f"Bearer {os.environ['VBA_KEY']}"}, ) print(r.json()["data"])
const res = await fetch("https://api.volleyballapi.com/v1/competitions/cp_kxgcx249/rosters", { 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-11-12, with long lists cut short.
200 application/json
{
"data": {
"competition": {
"id": "cp_kxgcx249",
"name": "XXI Central American VB U-21 Women - Honduras 2026",
"discipline": "indoor",
"gender": "women",
"season": 2026
},
"teams": [
{
"team": { "id": "tm_tzkxkfja", "name": "Belize" },
"players": [
{
"player": { "id": "pl_xj4xz9td", "name": "Emaun Marin" },
"shirt": "1",
"captain": false,
"libero": false,
"position": "2",
"nationality": "BIZ",
"birth_date": "2010-03-11",
"height_cm": 179
},
{
"player": { "id": "pl_196h5txb", "name": "Nathalie Popper" },
"shirt": "2",
"captain": false,
"libero": false,
"position": "3",
"nationality": "BIZ",
"birth_date": "2011-02-03",
"height_cm": 182
},
{
"player": { "id": "pl_4y3s7692", "name": "Chloe Bowman" },
"shirt": "3",
"captain": false,
"libero": false,
"position": "2",
"nationality": "BIZ",
"birth_date": "2011-12-20",
"height_cm": 169
},
{
"player": { "id": "pl_k55q520n", "name": "Sara Safa" },
"shirt": "4",
"captain": true,
"libero": false,
"position": "1",
"nationality": "BIZ",
"birth_date": "2009-10-29",
"height_cm": 168
},
...
]
},
{
"team": { "id": "tm_0s20hcq1", "name": "Costa Rica" },
"players": [
{
"player": { "id": "pl_qjdgzcef", "name": "Esmeralda Ugalde Hernandez" },
"shirt": "2",
"captain": false,
"libero": false,
"position": "2",
"nationality": "CRC",
"birth_date": "2010-02-16",
"height_cm": 175
},
{
"player": { "id": "pl_6nb4s7n9", "name": "Nathalia Zavaleta Méndez" },
"shirt": "6",
"captain": false,
"libero": false,
"position": "6",
"nationality": "CRC",
"birth_date": "2008-04-20",
"height_cm": 176
},
{
"player": { "id": "pl_ytbnr1v7", "name": "Kristina Vargas Mbeki" },
"shirt": "8",
"captain": false,
"libero": false,
"position": "1",
"nationality": "CRC",
"birth_date": "2008-10-21",
"height_cm": 172
},
{
"player": { "id": "pl_pcxt3nge", "name": "Nadia Lucía Granados Salazar" },
"shirt": "9",
"captain": false,
"libero": false,
"position": "1",
"nationality": "CRC",
"birth_date": "2008-09-06",
"height_cm": 168
},
...
]
},
{
"team": { "id": "tm_7bvptfb9", "name": "El Salvador" },
"players": [
{
"player": {
"id": "pl_qc68pd0d",
"name": "Fiorella Abigail Apontes Di Majo"
},
"shirt": "1",
"captain": false,
"libero": true,
"position": "4",
"nationality": "ESA",
"birth_date": "2008-09-22",
"height_cm": 153
},
{
"player": {
"id": "pl_pnypmj29",
"name": "Galilea Fernanda Guardado Batres"
},
"shirt": "2",
"captain": false,
"libero": false,
"position": "6",
"nationality": "ESA",
"birth_date": "2009-06-30",
"height_cm": 170
},
{
"player": {
"id": "pl_9z3argd2",
"name": "Larissa Milagros Rodriguez Diaz"
},
"shirt": "3",
"captain": false,
"libero": false,
"position": "1",
"nationality": "ESA",
"birth_date": "2010-11-11",
"height_cm": 175
},
{
"player": {
"id": "pl_ahwgdmdg",
"name": "Tatiana Valeria Gomez Alvarado"
},
"shirt": "4",
"captain": false,
"libero": false,
"position": "2",
"nationality": "ESA",
"birth_date": "2010-05-13",
"height_cm": 162
},
...
]
},
{
"team": { "id": "tm_vfhtv517", "name": "Guatemala" },
"players": [
{
"player": {
"id": "pl_8mdf4r34",
"name": "Appril Larissa García García"
},
"shirt": null,
"captain": false,
"libero": false,
"position": "2",
"nationality": "GUA",
"birth_date": "2012-03-03",
"height_cm": 168
},
{
"player": { "id": "pl_gmtsfhcx", "name": "Isabel Herrera García" },
"shirt": "1",
"captain": false,
"libero": false,
"position": "2",
"nationality": "GUA",
"birth_date": "2012-04-09",
"height_cm": 170
},
{
"player": {
"id": "pl_96vb4n3k",
"name": "Melissa Daniela Guerra Morataya"
},
"shirt": "2",
"captain": true,
"libero": false,
"position": "6",
"nationality": "GUA",
"birth_date": "2009-02-23",
"height_cm": 171
},
{
"player": { "id": "pl_aepf86s8", "name": "Daniela Falla Hegel" },
"shirt": "3",
"captain": false,
"libero": false,
"position": "3",
"nationality": "GUA",
"birth_date": "2012-04-25",
"height_cm": 174
},
...
]
},
...
]
},
"meta": { "plan": "Complete", "teams": 7, "players": 152 }
}Fields
| Field | Type | What it holds |
|---|---|---|
competition | object | id, name, discipline, gender and season |
teams | array | One entry a team: team (id and name) and players |
players[].player | object | id and name |
players[].shirt | string | Shirt number |
players[].captain, players[].libero | bool | Captain and libero |
players[].position | string | Position where the registration gives one, else null |
players[].nationality | string | Three-letter federation code |
players[].birth_date, players[].height_cm | date, int | Where known |
meta.teams, meta.players | int | Teams and players in the answer |
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 |
| 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.
Stuck on something?
Ask support