GET /get-/buckets

Retrieves a paginated list of all object storage buckets associated with your project. Supports filtering by region, name prefix, and tags. Returns bucket metadata including storage class, creation date, and current size.

Requires: API_KEY or Bearer Token Scope: storage:read Rate Limit: 60 req/min

Query Parameters

Name	Type	Required	Description
limit	integer	Optional	Maximum number of buckets to return. Default: 25, Max: 100.
offset	integer	Optional	Number of buckets to skip for pagination.
prefix	string	Optional	Filter buckets by name prefix.
region	string	Optional	Filter by data center region (e.g., `us-east-1`, `eu-west-2`).
tag	string	Optional	Filter buckets containing a specific tag key.

Request Example

cURL

Python

Node.js

cURL

curl -X GET \n  "https://api.cloudnexus.io/v1/get-/buckets?limit=25®ion=us-east-1" \n  -H "Authorization: Bearer <YOUR_API_KEY>" \n  -H "Content-Type: application/json"

Python

import requests

response = requests.get(
    "https://api.cloudnexus.io/v1/get-/buckets",
    params={"limit": 25, "region": "us-east-1"},
    headers={"Authorization": "Bearer <YOUR_API_KEY>"}
)
print(response.json())

Node.js

const axios = require('axios');

axios.get('https://api.cloudnexus.io/v1/get-/buckets', {
  params: { limit: 25, region: 'us-east-1' },
  headers: { 'Authorization': 'Bearer <YOUR_API_KEY>' }
})
.then(res => console.log(res.data))
.catch(err => console.error(err));

Response Example (200 OK)

JSON

{
  "data": [
    {
      "id": "bkt_7x92m4k1p0",
      "name": "prod-assets-us-east",
      "region": "us-east-1",
      "storage_class": "STANDARD",
      "created_at": "2024-08-12T14:32:00Z",
      "size_bytes": 48291034880,
      "object_count": 12847,
      "public": false,
      "tags": { "env": "production", "team": "frontend" }
    },
    {
      "id": "bkt_3n8q7w2v5x",
      "name": "backup-snapshots",
      "region": "eu-west-2",
      "storage_class": "GLACIER",
      "created_at": "2024-11-05T09:15:22Z",
      "size_bytes": 107374182400,
      "object_count": 342,
      "public": false,
      "tags": { "env": "production", "type": "backup" }
    }
  ],
  "pagination": {
    "total": 47,
    "limit": 25,
    "offset": 0,
    "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
  }
}

Status Codes

200 Successful request. Returns bucket list and pagination metadata.

401 Unauthorized. Missing or invalid API key/token.

403 Forbidden. Insufficient permissions (storage:read scope required).

429 Rate limit exceeded. Retry after Retry-After header value.

500 Internal server error. Contact support if persistent.

Notes

• Bucket names must be globally unique across all CloudNexus tenants.
• Use next_cursor in subsequent requests for cursor-based pagination instead of offset.
• Storage class options: STANDARD, INFREQUENT, GLACIER.
• Response includes soft-deleted buckets if ?include=deleted is passed.