> For the complete documentation index, see [llms.txt](https://docs.nebulablock.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nebulablock.com/api-reference/platform-api/list-workspaces/list-buckets.md).

# List Buckets

List the buckets in an object storage workspace with object counts, sizes, and privacy.

List every bucket in a workspace, with its object count, size, and privacy setting.

## HTTP Request

`GET` `{API_URL}/object-storage/buckets`

where `API_URL = https://api.nebulablock.com/api/v1`.

## Query Parameters

| Parameter             | Requirement | Type      | Description                                                                 |
| --------------------- | ----------- | --------- | --------------------------------------------------------------------------- |
| `object_storage_name` | Required    | `string`  | The workspace to list buckets from                                          |
| `team_id`             | Optional    | `integer` | Act on a team's storage instead of your own. See [Teams](/account/teams.md) |

## Response Attributes

#### data `list`

The buckets in the workspace. Each entry contains:

* **id** `string`: The bucket's full name, including the `u-<hash>-<workspace>.` prefix the platform adds at creation. This is the name `s3cmd` and the S3 API see. Buckets predating the storage migration have no prefix.
* **file\_num** `integer`: Number of objects in the bucket. **`null`** for an empty bucket, not `0`.
* **storage\_size** `string`: Total size, already formatted for display (for example `"1.4 GB"`) rather than returned as a byte count.
* **create\_time** `string`: When the bucket was created, as an ISO 8601 UTC timestamp (`2026-08-07T18:52:29.362000+00:00`).
* **private** `integer`: `1` when the bucket is private, `0` when public, or `null` if the privacy setting could not be read.

#### status `string`

`success` or `failed`.

#### message `string`

A description of the result.

## Example

#### Request

```bash
curl -X GET '{API_URL}/object-storage/buckets?object_storage_name=research-datasets' \
-H 'Authorization: Bearer {TOKEN}'
```

#### Response

```json
{
    "data": [
        {
            "id": "u-2f36933d-research.checkpoints",
            "file_num": 128,
            "storage_size": "42.7 GB",
            "create_time": "2026-03-14T09:21:07.221000+00:00",
            "private": 1
        }
    ],
    "message": "buckets data successfully retrieved",
    "status": "success"
}
```

## See also

* [Create Bucket](/api-reference/platform-api/list-workspaces/create-bucket.md)
* [List Files](/api-reference/platform-api/list-workspaces/list-files.md)
* [Toggle Bucket Privacy](/api-reference/platform-api/list-workspaces/toggle-bucket-privacy.md)