# List bucket events

> The bucket's change feed.

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

Every upload, code change, deletion, backup, restore and key action in the bucket, newest first.

## 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

- `bucket_id` (string, required): The bucket id (`cbk_…`).

## Query parameters

- `limit` (integer, default 50): How many to return, 1 to 100.
- `before` (string): A `created_at` (or `at`) timestamp: return items before it, for paging.
- `type` (string): Only this event type, or a prefix ending in a dot (`backup.`).

## Response

- `object` (string): Always `event`.
- `id` (string): The event id (`cbe_…`).
- `type` (string): What happened, like `upload.completed` or `backup.restored`. See [Events](/code-buckets/events) for the full list.
- `summary` (string): One line for people.
- `project_id / bucket_id` (string): Where it happened (`bucket_id` is `null` for project events).
- `actor` (object): Who did it: `{ type: "api_key", key_id, key_name }`, `{ type: "console" }` or `{ type: "system" }`.
- `data` (object): Details for the type (ids, sizes, refs).
- `at` (string): ISO 8601 timestamp.

## Example request

```bash
curl "https://api.codebuckets.clatterlabs.xyz/v1/buckets/BUCKET_ID/events?limit=20" \
  -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 bucket with that id on your account. |

## Example response

```json
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "cbe_7y2u5i8o1p4a6s9d3f0g",
      "type": "code.updated",
      "summary": "Code tree updated from storefront.zip: 1284 files, 3 kept in the archive only",
      "project_id": "cbp_4k9x2m7q1n8v3c6z0b5w",
      "bucket_id": "cbk_q7c1r9t2y6u0i3o8p5a4",
      "actor": {
        "type": "api_key",
        "key_id": "key_7f3a…",
        "key_name": "CI"
      },
      "data": {
        "object_id": "cbo_m2n8b4v6c1x9z3l7k5j0",
        "ref": "9b1f0c5e2a7d43e8b6c1f0a9d2e5b7c4a1f3e8d0",
        "files": 1284,
        "skipped": 3,
        "target_path": ""
      },
      "at": "2026-10-28T14:06:52.311Z"
    }
  ],
  "has_more": false,
  "next_before": null
}
```

The response is a list (`object`, `data`, `has_more`, `next_before`); the fields above describe each event in `data`.