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

# Events API

> Read the platform-wide event firehose, or stream events live via Server-Sent Events.

# Events API

A read-only feed of recent notable events in the platform — message sent, message delivered, agent run, flow step, contact updated, conversation created, webhook endpoint updated, etc. Two access patterns:

* **Polled** — `GET /api/v1/events` pages over a bounded recent-window replay buffer (see below).
* **Live** — `GET /api/v1/events/stream` opens an SSE connection that delivers events in real time.

<Warning>
  **This is not durable history.** The Events API is a bounded, in-memory replay
  buffer (a per-tenant Redis Stream), **not** a system of record. It retains only
  the **most recent \~5000 events per tenant**, and the buffer expires after \~15
  minutes of tenant inactivity. Older events are evicted and are **gone** — they
  cannot be paged back to. `GET /api/v1/events/{id}` resolves **only** ids still
  inside the current window; an evicted id returns `404`. If the real-time store
  is briefly unavailable the surface **degrades open** — the list returns an empty
  page and a single-event lookup returns `404` rather than erroring.

  For a durable, complete, retry-handled record of every event — anything you'd
  build a system of record, audit log, or reconciliation job off of — use
  [Webhooks](/webhooks/overview) instead. Do not treat this endpoint as an event log.
</Warning>

**Base path:** `/api/v1/events`

**Authentication:** API key (`X-API-Key`) or session JWT.

| Method | Path                    | Purpose                                                 |
| ------ | ----------------------- | ------------------------------------------------------- |
| `GET`  | `/api/v1/events/`       | List recent events from the replay window (paginated)   |
| `GET`  | `/api/v1/events/{id}`   | Get a single recent event — only if still in the window |
| `GET`  | `/api/v1/events/stream` | Subscribe via Server-Sent Events                        |

## Live stream — SSE

```bash theme={null}
curl -N "https://api.orbit.devotel.io/api/v1/events/stream?token=dv_live_sk_your_key_here"
```

Events arrive as `data:` lines (one JSON object per line). Reconnect on `error` with the `Last-Event-ID` header set so you don't lose events.

The `?token=` query parameter is promoted to `X-API-Key` server-side so browsers (which can't set arbitrary headers on EventSource) can authenticate. As with every Orbit endpoint, query strings are stripped from access logs platform-wide before they're written, so the token value is never persisted to log storage.

## Ingesting events — `POST /api/v1/events/track`

To **record** your own product events (rather than read the feed above), POST to
the ingestion endpoint with an `event` name, an optional contact identifier
(`contact_email` or `contact_phone` — omit both to store the event without
linking it to a contact), and an optional `properties` object:

```bash theme={null}
curl -X POST "https://api.orbit.devotel.io/api/v1/events/track" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "Order Placed",
    "contact_email": "buyer@example.com",
    "properties": { "order_id": "ord_123", "total_cents": 4999 }
  }'
```

<Warning>
  **`properties` payload ceiling — 1 MiB.** The serialized `properties` JSON for a
  single event must not exceed **1 MiB (1,048,576 bytes)**. An event over the
  ceiling is rejected with HTTP `413` and `error.code` =
  [`EVENT_PAYLOAD_TOO_LARGE`](/reference/error-codes#event_payload_too_large) —
  nothing is stored and the contact timeline is unchanged. Keep individual
  attributes small: store large blobs (raw documents, base64 media, full request
  dumps) in your own object storage and reference them from `properties` by URL
  or id rather than embedding them inline.
</Warning>

## See also

* [Webhooks](/webhooks/overview) — for delivered, durable, retry-handled push of the same events