SSE Reference

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

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"}

`leaks.finished`

Sent when all leak providers have finished or been skipped.

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 during registered-account checks.

event: registered_accounts
data: {"search_id":"d290f1ee-6c54-4b01-90e6-d701748f0851","event":"registered_accounts","type":"result","module":{"name":"Google"},"timestamp":"2026-05-27T12:00:06.000Z"}

`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.

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`

`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

​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`

`leaks.finished`

`registered_accounts`

`breached_accounts`

Sharding model

Resume and reconnection

Notes