# List events (/docs/api-reference/list_events)

`GET /v1/events` · operation `list_events`

Lists what happened, newest first, in one Room (room_id), about one business (business_id), to one task (task_id), or across your Workspace. Each event says who did it, through which app (SMB, Claude, ChatGPT, an API key), and what about; a .updated event's data.changes says what changed ({ status: { from: "in_progress", to: "done" } }). Same visibility as each Room's Activity. Filter by types (task.updated, file.*), actor (me or a user id), or about=me.

**Sign-in:** a signed-in person's access token (`Authorization: Bearer …`), which AI apps get through MCP sign-in; or a Workspace API key in the `X-SMB-API-Key` header.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `room_id` | string | no | Only this Room. |
| `business_id` | string | no | Only events about this business. |
| `task_id` | string | no | Only this task's events. |
| `actor` | `me` or string (uuid) | no | Only what this person did: me, or their user id. |
| `about` | `me` | no | me: tasks given to you, approvals asked of you, your shared apps read. |
| `types` | array of string | no | Types (task.updated) or kinds (file.*), comma-separated. To see only some changes, read data.changes on each event. |
| `since` | string | no | ISO date and time: only events since then. |
| `after` | string | no | next_cursor from the previous page. |
| `limit` | integer | no |  |

### Headers

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `SMB-Workspace-Id` | string (uuid) | yes | Workspace where this operation runs. Required for user tokens and Workspace API keys. |

### Response

**200** Successful authorized response.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of object | yes |  |
| `data[].id` | string | yes |  |
| `data[].type` | string | yes |  |
| `data[].occurred_at` | string | yes |  |
| `data[].room` | object or null | yes |  |
| `data[].actor` | object | yes |  |
| `data[].subject` | object or null | yes |  |
| `data[].about` | object or null | yes |  |
| `data[].data` | object | yes | What it carried. For a .updated event, data.changes is { field: { from, to } } for only the fields that changed (from is null when unknown or unset), next to context like file_name. |
| `data[].mine` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |
| `request_id` | string | yes |  |

### Errors

- `400` The request is invalid.
- `401` Authentication is required.
- `403` The caller is not authorized.
- `404` The resource was not found.
- `409` The resource revision or idempotency input conflicts.
- `413` The request body is too large.
- `415` The request must be JSON.
- `422` Required evidence is missing.
- `429` Rate limit reached; honor Retry-After.
- `500` The request could not be completed.
- `502` A dependency returned an invalid response.
- `503` The service is temporarily unavailable.

### Example

```bash
curl --request GET "https://api.smb.co/v1/events" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header "SMB-Workspace-Id: $WORKSPACE_ID"
```