Placement
See which nodes are responsible for which objects in a bucket.
| Endpoint | Method | Admin Required |
|---|---|---|
/api/v1/admin/cluster/placement | GET | Yes |
Returns, for each object matching a bucket (and optional prefix), which nodes are currently responsible for it - computed on the fly from the current membership and placement hash, never persisted. The first id in nodeIds is the primary (top-ranked) replica; the rest are secondary replicas.
Limited to the first 1000 objects matching the bucket/prefix (paginated on top of that fixed window) - a very large bucket's placement beyond the first 1000 objects isn't visible through this endpoint.
Query Parameters
bucket
string required
The bucket to inspect.
prefix
string
Only include keys starting with this prefix. Default: none (whole bucket).
nodeId
string
Only include keys for which this node is currently responsible (primary or secondary) - turns the browse into "which keys does this node hold," rather than requiring the caller to filter
nodeIds client-side. Default: none (every key in the bucket/prefix).page
integer
Page number. Default:
1per
integer
Items per page. Default:
25Response
{
"metadata": {
"page": 1,
"per": 25,
"total": 2
},
"items": [
{
"key": "logo.png",
"nodeIds": [
"B1C2D3E4-F5G6-7890-HIJK-LM1234567890",
"C2D3E4F5-G6H7-8901-IJKL-MN2345678901",
"D3E4F5G6-H7I8-9012-JKLM-NO3456789012"
],
"size": 15420
},
{
"key": "backup.tar.gz",
"nodeIds": [
"C2D3E4F5-G6H7-8901-IJKL-MN2345678901",
"D3E4F5G6-H7I8-9012-JKLM-NO3456789012",
"B1C2D3E4-F5G6-7890-HIJK-LM1234567890"
],
"size": 943820000
}
]
}
Response Fields
key
string
The object key.
nodeIds
array
Ids of every node currently responsible for this key, ordered by rank -
nodeIds[0] is the primary replica.size
integer
The object's size in bytes.
Errors
| Status | Reason |
|---|---|
400 | Missing bucket query parameter |