Streaming lookups
The same lookup as server sent events, with real progress.
A cold lookup can take tens of seconds while six providers are queried in two passes. This endpoint is the same lookup delivered as server sent events: you get a progress snapshot every time a dataset is planned or settles, then the finished report, so a client can show what is actually happening rather than a spinner.
GET /api/v1/lookup/stream?q={query}
The response is text/event-stream. The shallow, offline and refresh parameters apply as on every lookup endpoint.
Events
| Event | Payload | Meaning |
|---|---|---|
progress | Array of { provider, planned, settled } | A dataset was planned or finished. planned can grow while the lookup runs; that is the second pass adding work. |
report | The full lookup report | The answer. Can arrive twice: see late reports below. |
failed | { error, hint? } | The lookup failed, for example an unparseable query. |
Application failures arrive as the failed event, not error. The browser's EventSource reserves the error event for transport problems, so listening only to error would miss real failures.
Late reports
If the first report has meta.pendingDatasets above zero, a slow dataset was still running when the report was sent. The stream then stays open (up to about a minute) and delivers a second, completed report event when the dataset lands. If nothing is outstanding, the stream closes immediately after the first report. A dataset that failed will not arrive on this connection: its wait is in meta.retryAfterMs and picking it up means a new lookup later.
Example
const es = new EventSource(
"https://subnethistory.com/api/v1/lookup/stream?q=" +
encodeURIComponent("185.220.101.0/24")
);
es.addEventListener("progress", (e) => {
const providers = JSON.parse(e.data);
const settled = providers.reduce((n, p) => n + p.settled, 0);
const planned = providers.reduce((n, p) => n + p.planned, 0);
console.log(`datasets: ${settled}/${planned}`);
});
es.addEventListener("report", (e) => {
const report = JSON.parse(e.data);
render(report);
if (!report.meta.pendingDatasets) es.close();
});
es.addEventListener("failed", (e) => {
console.error(JSON.parse(e.data).error);
es.close();
});
curl -N "https://subnethistory.com/api/v1/lookup/stream?q=8.8.8.8"
The -N flag disables curl's buffering so events print as they arrive.
When to use it
Close the stream yourself once nothing is pending. An EventSource left open reconnects when the server closes the connection, and every reconnect is a fresh lookup.
Use the stream when a person is waiting and the subject might be cold. For batch enrichment, the plain lookup endpoints are simpler: fire the lookup, and if meta.partial is true, come back after meta.retryAfterMs to pick up the rest.