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

# Streaming events

> Consume Entity Search SSE batches, completion events, and in-stream errors.

Entity Search uses Server-Sent Events (SSE). Each complete frame is separated by a blank line and contains a `data:` payload.

## Successful sequence

1. Zero or more `entity_search_batch` events.
2. Exactly one `entity_search_done` event.
3. The terminal `data: [DONE]` sentinel.

### Batch event

```text theme={null}
data: {"object":"entity_search_batch","leads_search_id":"search_...","entity_type":"company","objective":"AI infrastructure startups","limit":20,"count":2,"cum_count":2,"batch_index":1,"finish":false,"entities":[...],"created_at":1785751200}

```

Important fields:

| Field             | Description                                                              |
| ----------------- | ------------------------------------------------------------------------ |
| `batch_index`     | Positive batch identifier. Use it to deduplicate client-side processing. |
| `count`           | Number of entities in this batch.                                        |
| `cum_count`       | Cumulative result count reported by the search.                          |
| `entities`        | Result objects for the batch.                                            |
| `leads_search_id` | Search-layer identifier, distinct from `X-Request-Id`.                   |

<Warning>
  A byte-for-byte duplicate batch may be forwarded again during upstream retry behavior. lev8 meters a repeated `batch_index` only once, but your consumer should also process each `batch_index` only once.
</Warning>

### Completion event

```text theme={null}
data: {"object":"entity_search_done","leads_search_id":"search_...","entity_type":"company","objective":"AI infrastructure startups","limit":20,"cum_count":2,"stop_reason":"source_finished","finish":true,"created_at":1785751203}

data: [DONE]

```

Known `stop_reason` values include `limit`, `source_finished`, `no_data_timeout`, and `rejected_streak`. Treat new values as forward-compatible strings.

## Errors after streaming starts

HTTP status can no longer change after response bytes have been sent. If a failure occurs after the stream starts, lev8 emits a redacted error object and then terminates the stream:

```text theme={null}
data: {"object":"error","error":{"type":"internal_error","message":"internal error","request_id":"req_..."}}

data: [DONE]

```

An `error` object means the search did not complete successfully, even though the HTTP status is `200`. Do not treat `[DONE]` by itself as success; require an `entity_search_done` event and no `error` event.

## Consumer checklist

* Parse complete SSE frames rather than arbitrary network chunks.
* Deduplicate `entity_search_batch` by `batch_index`.
* Preserve unknown fields for forward compatibility or ignore them safely.
* Treat `entity_search_done` followed by `[DONE]` as protocol completion.
* Treat an `error` event as failure and record its `request_id`.
* Set a client timeout long enough for your assigned search configuration.