Concepts

How a search works

A search is started once, runs on our side, and can be read as many times as you need within an hour of its end.

The three stages

Start · POST /api/v2/search

We validate the query, reserve 1 credit and start querying the sources. You get a search_id at once.

Stream · GET /api/v2/search/{search_id}

Each source that finds something sends a result. A source that fails sends a source_error. A progress arrives every 5 seconds.

Settle · done or failed

The last event says whether the credit was spent or refunded, and gives your new balance.

The search does not depend on your connection

Once started, the search runs to its end whether or not a stream is open. If your connection drops, reconnect to read the rest (Handling disconnections).

Sources that find nothing stay silent

A source with no result sends no event. It is only counted in progress.done.

Duration

A search on all networks can take several minutes. It is stopped after 15 minutes at most, with failed, reason max_duration, and the credit is refunded.

Retention and replay

Results are kept for 1 hour after the end. Within that hour, opening the stream again replays the whole search from the first event. After it, the stream answers 404.

Duplicate searches

Sending the same search again while it runs (same key, query, query_type and networks) does not start a second one. You get the search_id of the running search with a 200, and no credit is used. A double click or a retried request costs nothing.