# List buckets

> The buckets in a project.

`GET https://api.codebuckets.clatterlabs.xyz/v1/projects/{project_id}/buckets` (key permission: `buckets:read`)

Returns the project's buckets, newest first, with storage use.

## Authorizations

- `Authorization` (string, required): Your API key as a bearer token: `Bearer clsk_...`. Create keys in the [Console](https://console.clatterlabs.com/api-keys) with the Code Buckets permissions you need.
- `X-Clatter-Account` (string, required): The Account ID that owns the key, like `CL-7K2M9QXA`. Find it in Console › Settings. A missing value answers `401 missing_account_id`; someone else's answers `401 account_mismatch`.

## Path parameters

- `project_id` (string, required): The Project ID (`cbp_…`).

## Response

- `object` (string): `list`.
- `data` (Bucket[]): Buckets. See [Get a bucket](/api-reference/code-buckets/buckets/get) for the fields.
- `has_more` (boolean): Always `false` (up to 100 buckets per project).

## Example request

```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/projects/PROJECT_ID/buckets" \
  -H "Authorization: Bearer $CLATTER_API_KEY" \
  -H "X-Clatter-Account: $CLATTER_ACCOUNT_ID"
```

## Errors

| Status | Code | When |
| --- | --- | --- |
| `401` | `invalid_api_key / missing_account_id / account_mismatch` | The key or Account ID is wrong. |
| `402` | `quota_exceeded` | This month's free tokens are used up. |
| `403` | `insufficient_scope` | The key lacks the permission. |
| `404` | `not_found` | No project with that id on your account. |

## Example response

```json
{
  "object": "list",
  "data": [
    {
      "object": "bucket",
      "id": "cbk_q7c1r9t2y6u0i3o8p5a4",
      "project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
      "name": "web",
      "description": null,
      "preview": true,
      "visibility": "private",
      "code": {
        "ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
        "files": 1284,
        "bytes": 18734211
      },
      "storage": {
        "used_bytes": 131204115,
        "pending_bytes": 0,
        "limit_bytes": 10737418240
      },
      "encryption": {
        "algorithm": "AES-256-GCM",
        "key": "per-bucket data key, wrapped by a Clatter Labs master key"
      },
      "created_at": "2026-10-28T14:05:11.482Z",
      "updated_at": "2026-10-28T14:05:11.482Z"
    }
  ],
  "has_more": false
}
```