DocumentationTeams and players
Volleyball players API
GET/v1/players
Players found by name, with gender and federation.
Parameters
Parameters marked required must be sent; the rest are optional.
| Name | Type | What it does | Example |
|---|---|---|---|
q | text | Part of the name, 2 to 80 characters. Required. | Nilsson |
gender | enum | One of men, women, mixed. | men |
page | int | Page number, from 1. Adds totals to meta. | 2 |
per_page | int | Rows a page, 1 to 200. 50 when not sent. | 200 |
cursor | string | The next_cursor from the last answer. Send it alone. |
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.
# Players, found by name curl "https://api.volleyballapi.com/v1/players?q=Nilsson&per_page=3" \ -H "Authorization: Bearer $VBA_KEY"
$q = http_build_query(['q' => 'Nilsson', 'per_page' => '3']); $ch = curl_init('https://api.volleyballapi.com/v1/players?' . $q); 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/players", params={"q": "Nilsson", "per_page": "3"}, headers={"Authorization": f"Bearer {os.environ['VBA_KEY']}"}, ) print(r.json()["data"])
const res = await fetch("https://api.volleyballapi.com/v1/players?q=Nilsson&per_page=3", { headers: { "X-API-Key": process.env.VBA_KEY }, }); const { data, meta } = await res.json();
Response
Every answer is data plus meta. A first call with page adds totals to meta; a call with cursor carries only the next cursor, which is quicker over long ranges. This is a real answer to the request above, counted 2026-10-12, with long lists cut short.
{
"data": [
{
"id": "pl_n02ttkh0",
"name": "Nilsson My",
"gender": "men",
"federation": null
},
{
"id": "pl_aj6nz1jz",
"name": "Nilsson My",
"gender": "women",
"federation": null
},
...
],
"meta": {
"plan": "Complete",
"count": 3,
"next_cursor": "eyJvIjozLCJwIjozfQ",
"page": 1,
"per_page": 3,
"total": 49,
"total_pages": 17,
"next_page": 2,
"prev_page": null
}
}Fields
| Field | Type | What it holds |
|---|---|---|
id | string | Stable player id, pl_ |
name | string | Full name |
gender | enum | men or women |
federation | string | Three-letter federation code |
Errors
Errors come back as {"error": {"code", "message", "docs"}}, with plan and pricing added when a plan would answer. Every error.
| HTTP | Code | When |
|---|---|---|
| 400 | bad_request | A value of the wrong shape, or per_page outside 1 to 200, or a required parameter left out |
| 401 | unauthorized | No key, or a key that is not known or was revoked |
| 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.