---
title: stream
---

available in builds compiled with the `indexer_stream` feature. `/stream` is hydrant's ordered websocket event stream. each subscriber receives a full copy of the stream.

`/stream` is not wire- or protocol-compatible with [`tap`](../concepts/vs-tap.md). tap uses a sharded work queue, server-managed acknowledgements, and redelivery; hydrant uses broadcast delivery and client-managed cursors.

## GET /stream

subscribe to the ordered event stream.

### query parameters

| param | type | description |
| :--- | :--- | :--- |
| `cursor` | integer | inclusive `u64` event ID from which to replay durable record events. |

if `cursor` is omitted, the connection starts at the current stream head and receives only new events. if it is present, hydrant replays durable record events whose IDs are greater than or equal to the cursor, up to the head observed when the connection starts, then switches to live delivery.

`cursor=0` replays all retained record events. IDs are monotonic but may have gaps: live-only identity and account events consume IDs without being persisted, and events that cannot be inflated are skipped.

### event envelope

events are JSON text frames with this envelope:

```json
{
  "id": 42,
  "type": "record",
  "record": {}
}
```

| field | type | description |
| :--- | :--- | :--- |
| `id` | integer | `u64` stream event ID. |
| `type` | string | `record`, `identity`, or `account`. |
| `record` | object | present when `type` is `record`. |
| `identity` | object | present when `type` is `identity`. |
| `account` | object | present when `type` is `account`. |

only the payload matching `type` is present.

### record

record events are durable and available through cursor replay.

```json
{
  "id": 42,
  "type": "record",
  "record": {
    "live": true,
    "did": "did:plc:abc123xyz",
    "rev": "3kpjxabc123",
    "collection": "app.bsky.feed.post",
    "rkey": "3kpjxabc123",
    "action": "create",
    "record": {
      "$type": "app.bsky.feed.post",
      "text": "hello, world!",
      "createdAt": "2026-05-27T12:00:00.000Z"
    },
    "cid": "bafyreihy..."
  }
}
```

| field | type | description |
| :--- | :--- | :--- |
| `live` | boolean | `true` for live ingestion; `false` for backfill. |
| `did` | string | repository DID. |
| `rev` | string | repository revision TID. |
| `collection` | string | collection NSID. |
| `rkey` | string | record key. |
| `action` | string | `create`, `update`, or `delete`. |
| `record` | object | decoded DAG-CBOR record; omitted when no record content is stored. |
| `cid` | string | CID of `record`; omitted when no record content is stored. |

`record` and `cid` are omitted for deletes and when hydrant is configured not to store record content, including `HYDRANT_ONLY_INDEX_LINKS=true`.

### identity

identity events are live-only and are not available through cursor replay.

```json
{
  "id": 43,
  "type": "identity",
  "identity": {
    "did": "did:plc:abc123xyz",
    "handle": "user.bsky.social"
  }
}
```

| field | type | description |
| :--- | :--- | :--- |
| `did` | string | repository DID. |
| `handle` | string | current handle; omitted when unavailable. |

### account

account events are live-only and are not available through cursor replay.

```json
{
  "id": 44,
  "type": "account",
  "account": {
    "did": "did:plc:abc123xyz",
    "active": false,
    "status": "deactivated"
  }
}
```

| field | type | description |
| :--- | :--- | :--- |
| `did` | string | repository DID. |
| `active` | boolean | whether the repository is active. |
| `status` | string | account status; omitted when unavailable. |

### websocket behavior

- the server sends an empty ping every 30 seconds and responds to client ping frames with pong frames.
- client text and binary frames are not accepted; hydrant closes the connection when it receives one.
- if sending blocks for `HYDRANT_STREAM_SEND_TIMEOUT` (30 seconds by default), hydrant sends an error text frame and closes the connection:

```json
{
  "type": "error",
  "error": "ConsumerTooSlow",
  "message": "stream socket send blocked for at least 30 seconds"
}
```