Concepts

Handling disconnections

A search lasts minutes, and a connection that long will sometimes drop: network, proxy, load balancer, or a restart on our side. The search is not lost.

Resume a stream

Remember the last id

Every event carries an id, starting at 0. Keep the last one you received.

Reconnect with Last-Event-ID

When the connection drops, wait a few seconds, then open the stream again with the header Last-Event-ID: <that id>.

Receive the rest

The stream starts right after that event: none is missed, none is sent twice.

Stop on the last event

Stop when you receive done or failed.

Resume after event 75

curl -N https://dev.predictasearch.com/api/v2/search/$SEARCH_ID \
  -H "x-api-key: $API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Last-Event-ID: 75"

How long to retry

Keep retrying for at least 2 minutes, a few seconds apart. While our server restarts, connections are refused for up to about a minute. If it restarted during your search, the stream resumes with a failed event, reason shutdown or orphaned, and the credit is refunded.

Do not retry in a tight loop: more than 60 stream openings per minute are answered with 429.

Replay a whole search

Opening the stream without Last-Event-ID within 1 hour after the end sends the whole search again, from id: 0. Use it when your own process restarts and has lost what it had received.