SSE Reference

Use GET /search/{id}/stream to follow search execution in real time.

Temporary searches stream in the response to POST /search/temporary instead. Their stream uses the events below and cannot be resumed.

Concrete stream example

Run this against an existing SEARCH_ID:

curl -N -X GET "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer YOUR_API_KEY"

Typical successful session:

event: connected
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","timestamp":"2026-06-23T14:10:01.000Z"}

event: search.progress
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","status":"running","message":"orchestration started","timestamp":"2026-06-23T14:10:01.100Z"}

event: module.result
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","module":{"id":"github","name":"GitHub"},"card":{"github_001":{"username":"target","profile_url":"https://github.com/target"}},"timestamp":"2026-06-23T14:10:03.000Z"}

event: module.result
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","module":{"id":"gravatar","name":"Gravatar"},"card":{"gravatar_001":{"email_hash":"md5:...","profile_url":"https://gravatar.com/..."}},"timestamp":"2026-06-23T14:10:05.000Z"}

event: search.finished
data: {"search_id":"4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f","status":"completed","totals":{"module_results":2},"execution_time_ms":8120,"timestamp":"2026-06-23T14:10:09.000Z"}

Typical BYOK session (providers + completion):

event: connected
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","timestamp":"2026-06-23T14:20:01.000Z"}

event: byok.result
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"osint_industries","card":{"source":"github","username":"target","url":"https://github.com/target"},"timestamp":"2026-06-23T14:20:02.500Z"}

event: byok.result
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"sherlockeye","card":{"byok_sherlockeye":{"source":"social","handle":"target"}},"timestamp":"2026-06-23T14:20:03.100Z"}

event: byok.finished
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"osint_industries","status":"success","resultCount":7,"timestamp":"2026-06-23T14:20:06.900Z"}

event: byok.finished
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","provider":"sherlockeye","status":"no_results","resultCount":0,"timestamp":"2026-06-23T14:20:07.200Z"}

event: search.finished
data: {"search_id":"f1d0de6e-5f8e-42de-b88d-4b895be61d40","status":"completed","totals":{"module_results":7},"execution_time_ms":10004,"timestamp":"2026-06-23T14:20:11.000Z"}

Typical sharding/capacity session:

event: search.progress
data: {"search_id":"8d904b9c-60fa-4b33-a6ee-1bc6ab55ee8f","status":"running","message":"waiting runner capacity (status poll: 2 reachable, 0 available)","timestamp":"2026-06-23T14:25:00.000Z"}

event: search.progress
data: {"search_id":"8d904b9c-60fa-4b33-a6ee-1bc6ab55ee8f","status":"running","message":"shard 1/3 progress 4/12","result_cards_count":11,"timestamp":"2026-06-23T14:25:15.000Z"}

event: search.progress
data: {"search_id":"8d904b9c-60fa-4b33-a6ee-1bc6ab55ee8f","status":"running","message":"shard 2/3 progress 9/12","result_cards_count":26,"timestamp":"2026-06-23T14:25:22.000Z"}

Typical failed session:

event: connected
data: {"search_id":"95c36c17-f76e-4911-bd4e-8ea57515b2fb","timestamp":"2026-06-23T14:15:00.000Z"}

event: search.finished
data: {"search_id":"95c36c17-f76e-4911-bd4e-8ea57515b2fb","status":"failed","error":"NO_ELIGIBLE_RUNNER","timestamp":"2026-06-23T14:15:01.000Z"}

Event types

`connected`

Sent immediately after the SSE connection is established.

event: connected
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","timestamp":"2026-05-27T12:00:00.000Z"}

`module.result`

Sent when one module emits a result card.

event: module.result
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","module":{"id":"github","name":"GitHub"},"card":{"github_001":{"username":"target"}},"timestamp":"2026-05-27T12:00:02.000Z"}

Fields:

search_id: search UUID
module.id: module identifier when available
module.name: module display name
card: raw card payload
timestamp: event time

`search.progress`

Sent during orchestration and shard execution.

event: search.progress
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","status":"running","message":"shard 1/3 progress 6/18","result_cards_count":13,"timestamp":"2026-05-27T12:00:05.000Z"}

Fields:

status: queued or running
message: human-readable progress (for example capacity waits or shard progress)
result_cards_count: optional running count

`byok.result`

Sent when a BYOK provider emits one raw card event.

event: byok.result
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","provider":"osint_industries","card":{"source":"github","username":"target"},"timestamp":"2026-05-27T12:00:06.000Z"}

Fields:

provider: osint_industries or sherlockeye
card: provider-emitted card payload

`byok.finished`

Sent once per provider when provider execution completes.

event: byok.finished
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","provider":"sherlockeye","status":"success","resultCount":4,"timestamp":"2026-05-27T12:00:09.000Z"}

Possible status values:

success
no_results
failed

`search.finished`

Sent when the search reaches a terminal state.

event: search.finished
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","status":"completed","totals":{"module_results":1},"execution_time_ms":8234,"timestamp":"2026-05-27T12:00:08.000Z"}

Possible values for status:

completed
failed

Optional fields:

totals.module_results
execution_time_ms
error

`leak.status`

Sent for each leak source as it executes.

event: leak.status
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","leaked_code":"snusbase","status":"success","result_count":42,"timestamp":"2026-05-27T12:00:07.000Z"}

`leak.page.ready` (optional)

Sent when an early leak page has been stored and is readable, while the source can still be processing. Currently, Snusbase can publish its first page before the remaining pages are ready. This event contains a notification, not leak records. To receive it, send X-Osintly-Progressive-Leaks: 1 on the stream request. Use the same header on leak overview and leak-page requests. Setting it on POST /search does not opt subsequent requests in automatically.

curl -N "https://api.osint.ly/search/SEARCH_ID/stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Osintly-Progressive-Leaks: 1"

id: 91
event: leak.page.ready
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","leaked_code":"snusbase","page":1,"timestamp":"2026-10-06T12:00:04.000Z"}

Field	Meaning
`search_id`	Search UUID
`leaked_code`	Source key, such as `snusbase`
`page`	Available page number; currently the first page
`timestamp`	Event timestamp

On receipt, refresh Leaks Overview, then fetch the available page with the same opt-in header. During processing, the source count and pagination describe the published subset. For example, total_pages: 1 and has_next_page: false mean that no additional page is available yet; they do not mean that the source is complete. Refresh the overview again on the source’s terminal leak.status event or leaks.finished. Keep already-loaded pages, update the available page count, and load subsequent pages as needed. Deduplicate retried pages and records by page number and result key. A page-ready event does not guarantee later source success: retain error handling if a subsequent upload or provider step fails.

Without the opt-in header, this event is omitted, processing sources are not fetchable, and existing clients continue to retrieve finalized sources as before. Opting in does not change authentication, ownership checks, or the final response format. Not every source or search emits an early page event.

`leaks.finished`

Sent when all leak providers have finished or been skipped. This completes the leak phase, not the entire search. Modules and account checks may still be running; keep the stream open until search.finished.

event: leaks.finished
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","executed_codes":["snusbase"],"skipped_codes":["hudsonrock"],"failed_codes":[],"timestamp":"2026-05-27T12:00:08.000Z"}

`registered_accounts`

Sent as each email account-presence check completes. The module object carries the service identity, the found verdict, and, when available, a deletion guide describing how to remove the account.

event: registered_accounts
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","event":"registered_accounts","type":"result","module":{"check_id":"7c1f5f0e-6c54-4b01-90e6-d701748f0851","name":"Spotify","domain":"spotify.com","section":"Music & Audio","logo":"https://logos.osint.ly/spotify.com","description":"Music streaming service.","found":true,"deletion":{"url":"https://support.spotify.com/account_data/close-account/","difficulty":"medium","notes":"Use the Close your account flow and confirm by email.","email":null}},"timestamp":"2026-05-27T12:00:06.000Z"}

`module` field	Type	Description
`name` / `domain` / `logo`	string	Service identity.
`section`	string	Catalog category, for example `Social & Content`.
`found`	boolean	Whether an account exists for the searched email.
`deletion`	object or null	Deletion guide: `url`, `difficulty` (easy, medium, hard, impossible), `notes`, `email`.

Rate-limited or errored checks are not emitted on the public stream.

`breached_accounts`

Sent when breached-account aggregation is ready.

event: breached_accounts
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","event":"breached_accounts","resultCount":2,"results":[{"source":"BreachDirectory"}],"timestamp":"2026-05-27T12:00:08.000Z"}

Sharding model

For module execution, the orchestrator can split selected modules into shards and run them across multiple runners.

Max shard count is currently 3
Shards are assigned from runner capacity snapshots
If all runners are saturated, periodic search.progress events report waiting status
When capacity returns, execution resumes and progress messages include shard ratios (for example shard 2/3 progress 9/12)

Sharding details are implementation-level and may evolve, but these stream signals are stable integration points.

Resume and reconnection

Streams support resuming from an index:

Query params: start_index, cursor, or from
Header: Last-Event-ID

When available, each streamed event includes an SSE id: field. Store the last received id and reconnect from it after disconnects. Repeat the progressive opt-in header on every reconnect. Handle replayed notifications idempotently and ignore event types your client does not use. Group overview refreshes during bursts, but retain a trailing refresh if another notification arrives while a request is in progress. Fetch the final overview even if a short disconnect caused an early-page notification to be missed.

Notes

Keep the connection open until search.finished
The stream is additive: fetch GET /search/{id}/results for the normalized final payload
Leak results are retrieved separately through GET /search/{id}/results/leaks

API Overview

Endpoints

Concrete stream example

Event types

`connected`

`module.result`

`search.progress`

`byok.result`

`byok.finished`

`search.finished`

`leak.status`

`leak.page.ready` (optional)

`leaks.finished`

`registered_accounts`

`breached_accounts`

Sharding model

Resume and reconnection

Notes

​Concrete stream example

​Event types

​connected

​module.result

​search.progress

​byok.result

​byok.finished

​search.finished

​leak.status

​leak.page.ready (optional)

​leaks.finished

​registered_accounts

​breached_accounts

​Sharding model

​Resume and reconnection

​Notes

Concrete stream example

Event types

`connected`

`module.result`

`search.progress`

`byok.result`

`byok.finished`

`search.finished`

`leak.status`

`leak.page.ready` (optional)

`leaks.finished`

`registered_accounts`

`breached_accounts`

Sharding model

Resume and reconnection

Notes