> 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-files.md).

# List Files

List the objects in a bucket. Returns at most 1,000 entries and does not paginate.

List the objects in a bucket.

## HTTP Request

`GET` `{API_URL}/object-storage/bucket/files`

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

## Query Parameters

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

## Response Attributes

#### data `list`

The objects in the bucket. Each entry contains:

* **key** `string`: The object key, including any path prefix. Pass this as `object_key` to [Get Download URL](/api-reference/platform-api/list-workspaces/get-download-url.md), or in `file_keys` to [Delete File](/api-reference/platform-api/list-workspaces/delete-file.md).
* **hash** `string`: The object's content hash.
* **fsize** `string`: The object's size, already formatted for display rather than a byte count.
* **mimeType** `string`: The object's MIME type. May be `null` when the type was not recorded.
* **putTime** `string`: When the object was stored, as an ISO 8601 UTC timestamp (`2026-08-13T01:19:49.081000+00:00`).

#### status `string`

`success` or `failed`.

#### message `string`

A description of the result.

> **Important:** A `bucket_name` that does not exist also returns `200` with `"status": "success"` and an empty `data` array — identical to a real but empty bucket. This endpoint cannot tell you whether a bucket exists, and a typo returns nothing rather than an error. Use [List Buckets](/api-reference/platform-api/list-workspaces/list-buckets.md) to confirm a bucket is really there.

> **Important:** This endpoint returns **at most 1,000 objects** and takes no pagination or prefix parameters. The response gives no indication that it truncated — a bucket reporting `file_num: 1733` in [List Buckets](/api-reference/platform-api/list-workspaces/list-buckets.md) still returns only 1,000 entries here. Do not use this endpoint to enumerate a bucket. For anything that must be complete, list through the S3 API with `s3cmd ls` or an AWS SDK paginator — see [Python SDK](/products/object-storage/sdk-python.md).

## Example

#### Request

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

#### Response

```json
{
    "data": [
        {
            "key": "run-42/model.safetensors",
            "hash": "Fh8xVqod2MQ1VZr1AtNjWnR3rTRP",
            "fsize": "2.1 GB",
            "mimeType": "application/octet-stream",
            "putTime": "2026-08-14T18:35:02.417000+00:00"
        }
    ],
    "message": "bucket files data successfully retrieved",
    "status": "success"
}
```

## See also

* [Upload File](/api-reference/platform-api/list-workspaces/upload-file.md)
* [Get Download URL](/api-reference/platform-api/list-workspaces/get-download-url.md)
* [Delete File](/api-reference/platform-api/list-workspaces/delete-file.md)