Read as Markdown · Use with an AI agent
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 -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.
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.