> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Events & Analytics

> Query events, search content, view timelines, replay sessions, and analyze messaging metrics.

# Event Commands

The `omni events` command group provides event querying, search, analytics, and replay capabilities across all connected channels.

## `omni events list`

List events with filters.

```bash theme={"dark"}
omni events list [options]
```

| Option             | Description                                        |
| ------------------ | -------------------------------------------------- |
| `--instance <id>`  | Filter by instance ID                              |
| `--channel <type>` | Filter by channel type                             |
| `--type <type>`    | Filter by event type                               |
| `--chat-id <id>`   | Filter by chat ID                                  |
| `--since <time>`   | Events since (e.g., `24h`, `7d`, or ISO timestamp) |
| `--until <time>`   | Events until (ISO timestamp)                       |
| `--limit <n>`      | Limit results (default: 50)                        |

```bash theme={"dark"}
omni events list --since 24h
omni events list --instance <id> --type message.received --limit 100
omni events list --chat-id <id> --since 7d
```

## `omni events stream`

Stream events in real-time (`tail -f` style). Polls the event bus and prints new events as they arrive. `Ctrl+C` to stop.

```bash theme={"dark"}
omni events stream [options]
```

| Option             | Description                                                                   |
| ------------------ | ----------------------------------------------------------------------------- |
| `--instance <id>`  | Filter by instance ID (aliases: `--instance-ids`, `--instances`)              |
| `--channel <type>` | Filter by channel type                                                        |
| `--type <type>`    | Filter by event type                                                          |
| `--chat-id <id>`   | Filter by chat ID                                                             |
| `--person-id <id>` | Filter by person ID                                                           |
| `--since <time>`   | Start cursor (e.g., `5min`, `24h`, `7d`, or ISO timestamp)                    |
| `--errors-only`    | Show only error/failure events                                                |
| `--all`            | Include noisy event types (`presence`, `delivered`, `read`, `progress`)       |
| `--ndjson`         | Emit JSON Lines (one event per line) — same as global `--json` in stream mode |
| `--poll-ms <n>`    | Polling interval in milliseconds (default: `2000`)                            |

```bash theme={"dark"}
# Tail every event for one instance
omni events stream --instance my-whatsapp

# Watch failures only across all instances
omni events stream --errors-only

# Pipe to jq for ad-hoc filters
omni events stream --ndjson | jq 'select(.type == "message.received")'

# Stream the last hour and continue
omni events stream --since 1h
```

<Tip>
  `--ndjson` is the right output mode for piping. The default human-readable stream renders ANSI colors and is hard to parse; `--ndjson` (or the global `--json`) emits one event per line, ready for `jq` / `awk` / your event-bus consumer.
</Tip>

***

## `omni events search`

Full-text search across event content.

```bash theme={"dark"}
omni events search <query> [options]
```

| Option           | Description                      |
| ---------------- | -------------------------------- |
| `--since <time>` | Events since (e.g., `24h`, `7d`) |
| `--limit <n>`    | Limit results (default: 50)      |

```bash theme={"dark"}
omni events search "deployment" --since 7d
omni events search "error" --limit 20
```

## `omni events timeline`

Show the event timeline for a specific person.

```bash theme={"dark"}
omni events timeline <person-id> [options]
```

| Option        | Description                 |
| ------------- | --------------------------- |
| `--limit <n>` | Limit results (default: 50) |

```bash theme={"dark"}
omni events timeline <person-uuid> --limit 100
```

## `omni events metrics`

Get event processing metrics — throughput, latency, queue depth.

```bash theme={"dark"}
omni events metrics
```

## `omni events analytics`

Show event analytics summary.

```bash theme={"dark"}
omni events analytics [options]
```

| Option            | Description                                        |
| ----------------- | -------------------------------------------------- |
| `--instance <id>` | Filter by instance ID                              |
| `--since <time>`  | Events since (e.g., `24h`, `7d`, or ISO timestamp) |
| `--all-time`      | Show all-time stats (default: last 24h)            |

```bash theme={"dark"}
omni events analytics
omni events analytics --instance <id> --since 7d
omni events analytics --all-time
```

## `omni events replay`

Start, manage, or monitor event replay sessions. Replays re-process historical events through the automation pipeline.

```bash theme={"dark"}
omni events replay [options]
```

| Option            | Description                                   |
| ----------------- | --------------------------------------------- |
| `--start`         | Start a new replay session                    |
| `--since <time>`  | Replay events since (required with `--start`) |
| `--until <time>`  | Replay events until                           |
| `--types <types>` | Comma-separated event types to replay         |
| `--instance <id>` | Filter by instance ID                         |
| `--speed <n>`     | Speed multiplier                              |
| `--dry-run`       | Dry run (don't actually process)              |
| `--status <id>`   | Get status of a replay session                |
| `--cancel <id>`   | Cancel a replay session                       |

```bash theme={"dark"}
# Start a replay of last 24h message events
omni events replay --start --since 24h --types message.received

# Dry run first
omni events replay --start --since 7d --dry-run

# Replay at 5x speed
omni events replay --start --since 24h --speed 5

# Check replay status
omni events replay --status <session-id>

# Cancel a running replay
omni events replay --cancel <session-id>
```

<Warning>
  `omni events replay --start` re-runs every matching event through the live automation pipeline by default. Always run with `--dry-run` first on production instances — replays send real messages, call real webhooks, and can spam customers if filters are wrong.
</Warning>

## See also

<CardGroup cols={2}>
  <Card title="Automations" icon="robot" href="/omni/cli/automations">
    Trigger actions on the events surfaced here.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/omni/cli/webhooks">
    Push events to external services for custom processing.
  </Card>
</CardGroup>