list_events
Retrieve bridge events from the event log with optional filtering by type and notability. Supports cursor pagination for incremental reading.
Instructions
Return bridge events whose ts > since, oldest first.
The event log records dispatch starts/ends, schedule ticks, sentinel hits, schedule completions, webhook outcomes, and recovery actions. The buffer is bounded (default 1000 events) and persisted across bridge restarts.
Two read modes:
Debug mode (
notable_only=False, the default): every event. Good for forensic post-mortem of a workflow.Surfacing mode (
notable_only=True): only state transitions worth reporting to a human — terminal dispatch states, schedule completions / cancellations / errors, webhook failures, recovery actions. Skipsdispatch_start,schedule_tick,schedule_created,webhook_sent, andbridge_init_subprocess_alive. This is what an orchestrator wants for "what should I tell the user about?".
Cursor pattern: pass since=0 for everything, then on each
subsequent call pass the largest ts you saw.
types is an explicit allow-list — composes with
notable_only (intersection).
Common types:
Dispatch lifecycle:
dispatch_start,dispatch_end,dispatch_cancelled,dispatch_abandoned,dispatch_error,dispatch_orphan_finalized.Schedule lifecycle:
schedule_created,schedule_tick,schedule_activated,schedule_self_cancelled,schedule_cancelled,schedule_completed,schedule_tick_error.Webhook outcomes:
webhook_sent,webhook_failed.Recovery:
bridge_init_recovery,bridge_init_subprocess_alive.
Each event has ts (epoch seconds), event (type), plus
type-specific fields (job_id, schedule_id, channel,
ok, duration_ms, etc.).
Note: events generated before this feature shipped are gone — the
in-memory buffer only captures from the current bridge process
onward. Anything you persisted before then lives in the optional
CLAUDE_BRIDGE_LOG JSONL file (if you enabled it).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | ||
| limit | No | ||
| types | No | ||
| notable_only | No |