Skip to content
DocsOpenAPI spec

    List Buckets

    $ nirvana storage:buckets list
    GET/v1/storage/buckets

    List all Buckets

    ParametersExpand Collapse
    --project-id: string

    Project ID of resources to request

    --cursor: optional string

    Pagination cursor returned by a previous request. Only valid for the same filters and sort order.

    --limit: optional number

    Maximum number of items to return

    --name: optional string

    Filter by a case-insensitive substring of the Bucket name

    --region: optional string

    Filter by region

    --sort: optional string

    Comma-separated sort terms in precedence order, each field:asc or field:desc. Fields: created_at, updated_at, name, status, size_bytes, object_count

    --status: optional "pending" or "creating" or "updating" or 3 more

    Filter by Bucket status

    --tag: optional array of string

    Filter by tags. Repeat the parameter to require several tags; a Bucket must carry all of them.

    ReturnsExpand Collapse
    bucket_list: object { items, pagination }
    items: array of Bucket { id, created_at, endpoint, 10 more }
    id: string

    Unique identifier for the Bucket.

    created_at: string

    When the Bucket was created.

    endpoint: string

    S3 endpoint of the Bucket’s region. Point S3 clients at it, with an Object Storage Key of the same project and region.

    name: string

    Name of the Bucket, used to address it over S3.

    object_count: number

    Number of objects in the Bucket. Updated periodically, so it can lag behind recent writes.

    project_id: string

    Project ID the Bucket belongs to.

    region: "us-sva-2" or "us-wdc-1"

    Region the resource is in.

    "us-sva-2"
    "us-wdc-1"
    signing_region: string

    Region S3 clients must sign their requests for (the SigV4 region). Configure it as the region of any S3 client or SDK used with the Bucket.

    size_bytes: number

    Total size of the objects in the Bucket, in bytes. Updated periodically, so it can lag behind recent writes.

    status: "pending" or "creating" or "updating" or 5 more

    Status of the resource.

    "pending"
    "creating"
    "updating"
    "ready"
    "deleting"
    "deleted"
    "error"
    "suspended"
    tags: array of string

    Tags attached to the Bucket.

    updated_at: string

    When the Bucket was updated.

    url: string

    Path-style URL of the Bucket.

    List Buckets

    nirvana storage:buckets list \
      --api-key 'My API Key' \
      --project-id project_id
    {
      "items": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "created_at": "2025-01-01T00:00:00Z",
          "endpoint": "https://s3.sva2.nirvanacloud.io",
          "name": "my-bucket",
          "object_count": 1024,
          "project_id": "123e4567-e89b-12d3-a456-426614174000",
          "region": "us-sva-2",
          "signing_region": "us-east-1",
          "size_bytes": 1073741824,
          "status": "ready",
          "tags": [
            "production",
            "ethereum"
          ],
          "updated_at": "2025-01-01T00:00:00Z",
          "url": "https://s3.sva2.nirvanacloud.io/my-bucket"
        }
      ],
      "pagination": {
        "next_cursor": "RhwniMT4B74siYZcPF8TnCdGI1l9rpPvg",
        "previous_cursor": "ARhwnmi1hA7wEbHbMjdYQlOB_ZusP4fYvw",
        "total_count": 125
      }
    }
    Returns Examples
    {
      "items": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "created_at": "2025-01-01T00:00:00Z",
          "endpoint": "https://s3.sva2.nirvanacloud.io",
          "name": "my-bucket",
          "object_count": 1024,
          "project_id": "123e4567-e89b-12d3-a456-426614174000",
          "region": "us-sva-2",
          "signing_region": "us-east-1",
          "size_bytes": 1073741824,
          "status": "ready",
          "tags": [
            "production",
            "ethereum"
          ],
          "updated_at": "2025-01-01T00:00:00Z",
          "url": "https://s3.sva2.nirvanacloud.io/my-bucket"
        }
      ],
      "pagination": {
        "next_cursor": "RhwniMT4B74siYZcPF8TnCdGI1l9rpPvg",
        "previous_cursor": "ARhwnmi1hA7wEbHbMjdYQlOB_ZusP4fYvw",
        "total_count": 125
      }
    }