Entity Search uses Server-Sent Events (SSE). Each complete frame is separated by a blank line and contains a data: payload.
Successful sequence
- Zero or more
entity_search_batch events.
- Exactly one
entity_search_done event.
- The terminal
data: [DONE] sentinel.
Batch event
Important fields:
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.
Completion event
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:
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.
