# Streaming searches with SSE

Watch a supported search make progress, then read its final JSON envelope. Streaming changes delivery, while the normal request pipeline still handles collection and billing.

## Request a supported stream

search/all and search/creators accept stream=1 or stream=true. Other operations do not acquire streaming support from this parameter. Read their current parameters and prices before starting, and use a capped API key. Native browser EventSource cannot supply your x-api-key header; use server-side fetch to keep the credential private.

**curl · live progress**

```
curl -N 'https://www.monocrawl.com/v1/search/all?query=developer%20tools&stream=1' \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Idempotency-Key: REPLACE_WITH_YOUR_SAVED_UNIQUE_KEY'
```

## Parse named events, not network chunks

| Event | What to do |
| --- | --- |
| plan | Read the planned source work. This is progress information, not a separate approval step. |
| source-started / source-completed | Display source progress and reported outcomes. Do not count progress cost fields as customer credit receipts. |
| cost / enrichment-completed | Record optional progress information. Events vary by search and enabled work. |
| result | Read the final Monocrawl envelope, including success, data, credits_used, request_id and warnings. |
| error or EOF before result | No confirmed final outcome. Preserve the request context and reconcile; a lost stream does not prove failure or refund. |

The stream can begin with HTTP 200 and finish with a failed result envelope. Check Content-Type before parsing: an early refusal can be ordinary JSON. Decode UTF-8 incrementally, join data lines until the blank event delimiter, and tolerate unknown progress events.

- [Download incremental SSE parser](https://www.monocrawl.com/examples/search-stream.mjs)

## Disconnects and replay

Disconnecting the client does not cancel the server-side request. Do not use an automatically reconnecting client to start replacement searches. A client deadline bounds waiting, not server spend. The stream has no Last-Event-ID progress-resume contract.

Save an Idempotency-Key before the initial request. The streaming route passes the request to the same idempotency pipeline as direct JSON retrieval. A replay can provide a final result without the earlier progress events; it is not a replay of the event timeline. Use the same endpoint, filters, identity and key to recover the same logical request. A new search requires a new key.

Replayed receipts preserve the original charge and historical balance, with no new debit. A pending reconciliation outcome remains unresolved. Retain the original key and request ID, and use current balance and usage records to investigate.

- [Idempotency contract](https://www.monocrawl.com/docs/api-reference#idempotency)

- [Errors](https://www.monocrawl.com/docs/errors)

- [Credit accounting](https://www.monocrawl.com/docs/credits)