Streaming results

You are reading the v1 reference. v1 keeps working unchanged; new capabilities (several identities per request, risk scores, richer module data) are in v2. See migrating from v1.

A full lookup checks hundreds of platforms. Streaming means you show the first matches in well under a second instead of waiting for the slowest one.

Opening the stream

GET /v1/lookup/stream

curl -N "https://api.digifootprint.dev/v1/lookup/stream?query=someone@example.com" \
  -H "Authorization: Bearer dfp_your_key"

Depth on a stream

The stream accepts ?deep=true to sweep the full platform set including the long tail. It is the natural pairing: a deep lookup takes the longest, and streaming is what stops that from meaning a long blank wait.

?instant=true does the opposite: the same high-signal subset the batch instant path uses, closed at a latency ceiling. Results still arrive as each check resolves; the ceiling only decides when the stream ends. Use it when you want progressive results but cannot wait for a full sweep - a typical instant stream closes in under a second, against roughly twelve seconds for a standard one.

Its done event carries three extra fields: instant, deadlineMs, and platformsPending - how many checks were still in flight when the ceiling fired. Anything still pending is omitted, never reported as “not registered”. On any depth, done also carries lockedPlatforms when the account’s plan held some platforms back - see the lookup reference.

Event types

Five named events. platform_result fires many times, once per confirmed platform, and the others fire at most once each. done carries the same summary counts as the non-streamed response and closes the stream.

Event stream

event: platform_result
data: {"platform":"github","registered":true,"method":"public_api","checkedAt":"..."}

event: platform_result
data: {"platform":"reddit","registered":false,"method":"public_api","checkedAt":"..."}

event: breach_result
data: {"breaches":[{"name":"Adobe","date":"2013-10-04"}]}

event: done
data: {"lookupId":"8f2c...","platformsChecked":844,"matches":3,"socialMatches":2,"servedFromCache":false}

# with ?instant=true, done also carries:
# {"instant":true,"deadlineMs":900,"platformsPending":11}

In the browser

EventSource cannot send an Authorization header, so proxy the stream through your own backend and attach the key there. That is a feature, not an obstacle: your API key should never reach a browser in the first place.

Client

const source = new EventSource(url); // attach the key server-side

source.addEventListener('platform_result', (event) => {
  const result = JSON.parse(event.data);
  render(result);            // paint as each one lands
});

source.addEventListener('done', (event) => {
  const summary = JSON.parse(event.data);
  source.close();            // the stream ends here
});