> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://platform.bctrl.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# events Commands

> Manage events

Manage events

Output formatting flags (`--json`, `--jq`, and `--template`) are documented once in [Output Formatting](/cli/output) and are omitted from the tables below.

## `bctrl events get`

Read one Event by its ID.

```bash
bctrl events get <eventId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl events list`

List immutable Events visible in the organization, subaccount and selected Space: every kind of Event, read in one place. Filter by browser, sandbox, Run, Task, Conversation (its history), agent, category (audit logs are the always-on categories), type, actor, channel, outcome or time.

```bash
bctrl events list [flags]
```

| Flag                     | Description                                        |
| ------------------------ | -------------------------------------------------- |
| `--query <json>`         | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`        | Alias for --query                                  |
| `--browser <value>`      | Query parameter browser                            |
| `--sandbox <value>`      | Query parameter sandbox                            |
| `--run <value>`          | Query parameter run                                |
| `--task <value>`         | Query parameter task                               |
| `--conversation <value>` | Query parameter conversation                       |
| `--agent <value>`        | Query parameter agent                              |
| `--category <value>`     | Query parameter category                           |
| `--type <value>`         | Query parameter type                               |
| `--actor <value>`        | Query parameter actor                              |
| `--actor-type <value>`   | Query parameter actorType                          |
| `--channel <value>`      | Query parameter channel                            |
| `--outcome <value>`      | Query parameter outcome                            |
| `--from <value>`         | Query parameter from                               |
| `--to <value>`           | Query parameter to                                 |
| `--cursor <value>`       | Query parameter cursor                             |
| `--order <value>`        | Query parameter order                              |
| `--limit <value>`        | Query parameter limit                              |
| `--headers <json>`       | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`   | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`   | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`   | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl events stream`

Stream the same Events as they are committed, with the same filters. Resume after an Event ID with Last-Event-ID or after: the stream is in commit order, so a resumed stream has no gaps.

```bash
bctrl events stream [flags]
```

| Flag                          | Description                                        |
| ----------------------------- | -------------------------------------------------- |
| `--query <json>`              | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`             | Alias for --query                                  |
| `--browser <value>`           | Query parameter browser                            |
| `--sandbox <value>`           | Query parameter sandbox                            |
| `--run <value>`               | Query parameter run                                |
| `--task <value>`              | Query parameter task                               |
| `--conversation <value>`      | Query parameter conversation                       |
| `--agent <value>`             | Query parameter agent                              |
| `--category <value>`          | Query parameter category                           |
| `--type <value>`              | Query parameter type                               |
| `--actor <value>`             | Query parameter actor                              |
| `--actor-type <value>`        | Query parameter actorType                          |
| `--channel <value>`           | Query parameter channel                            |
| `--outcome <value>`           | Query parameter outcome                            |
| `--from <value>`              | Query parameter from                               |
| `--to <value>`                | Query parameter to                                 |
| `--after <value>`             | Query parameter after                              |
| `--headers <json>`            | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`        | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`        | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`        | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--last-event-id <id>`        | Resume the event stream after this event           |
| `--timeout-ms <milliseconds>` | End the stream after this duration (1–60000)       |
| `--max-events <number>`       | End after this many SSE events (1–200)             |