Streams
Material company events and new insider cluster buys pushed to you as they are processed, over one long-lived connection, instead of polling for them. Everything else in the API is request/response; these two endpoints are the exception. Most of this page uses the event stream; the cluster-buy stream works the same way.
Connect
The stream is a Server-Sent Events endpoint. Authentication is the same as everywhere else — your key as a bearer token — and the connection stays open until you close it.
curl --no-buffer -H "Authorization: Bearer $ALGOUM_API_KEY" \
"https://api.algoum.de/v1/events/stream"Two optional filters narrow it down: ticker for a single company and event_type for one kind of event. Filtering happens on our side, so a narrow filter also means less traffic for you.
curl --no-buffer -H "Authorization: Bearer $ALGOUM_API_KEY" \
"https://api.algoum.de/v1/events/stream?event_type=bankruptcy"What arrives on the wire
Every message uses the event name event and carries one event as JSON — the same shape the event endpoints return, without the response envelope. Every 30 seconds without traffic, the server sends the comment line : keepalive so that a dead connection is noticed instead of looking idle.
event: event
data: {"ticker":"XYZ","cik":"0001234567","event_type":"bankruptcy","item_code":"1.03","title":"Chapter 11 Bankruptcy Filing","event_date":"2026-07-15","filed_at":"2026-07-15T13:42:00-04:00","filing_id":"fil_0001234567-26-000045","source_url":"https://www.sec.gov/Archives/edgar/data/1234567/..."}
: keepalive
event: event
data: {"ticker":"ABC","cik":"0000998877","event_type":"leadership_change","item_code":"5.02","title":"Departure of Chief Financial Officer","event_date":"2026-07-15","filed_at":"2026-07-15T13:48:00-04:00","filing_id":"fil_0000998877-26-000012","source_url":"https://www.sec.gov/Archives/edgar/data/998877/..."}
What to expect from the timing
Measured over 14 days of live operation, an event reached a connected client a median of 39.8 seconds after the filing was accepted at the SEC — about 18 seconds of which pass at the SEC itself, before the filing shows up in its feed at all. This is a push within seconds, not within milliseconds, and it is an observation rather than a promised figure. It starts when the filing is accepted, which is itself up to four business days after the event.
Reconnecting: catch up, then listen
Messages carry no ID, so a reconnect does not replay what you missed while you were away. Cover the gap explicitly: after a drop, read the recent events for the window you were disconnected, then start listening again. /events/recent takes a minutes window of up to seven days.
curl -H "Authorization: Bearer $ALGOUM_API_KEY" \
"https://api.algoum.de/v1/events/recent?minutes=15&limit=500"Because catching up and listening can overlap, expect to see an event twice and de-duplicate on filing_id. Reconnect with a growing delay rather than immediately — the rate limit applies to connection attempts too.
Keep up, or you will miss messages
Each connection has a small send buffer. A client that reads slower than events arrive has messages dropped rather than queued forever, because one slow reader must not hold up everyone else. Do as little as possible in the receive loop: hand each event to a queue or a database and do the real work elsewhere.
Not from browser JavaScript
A browser’s built-in EventSource cannot send an Authorization header, and the API accepts the key in no other place. Consume the stream from your own backend — as in the example below — and push to your users from there. In the browser it is only possible through a streaming fetch, which brings the key into code your visitors can read; that is not a good trade for an API key.
A complete client
Node.js 18 or newer, no dependencies. It catches up first, then listens, de-duplicates, and reconnects with a growing delay:
const KEY = process.env.ALGOUM_API_KEY
const STREAM = "https://api.algoum.de/v1/events/stream"
const CATCH_UP = "https://api.algoum.de/v1/events/recent"
// Everything received since the process started, so a reconnect can skip what
// has already been handled.
const seen = new Set()
async function catchUp(minutes) {
const response = await fetch(`${CATCH_UP}?minutes=${minutes}&limit=500`, {
headers: { Authorization: `Bearer ${KEY}` },
})
if (!response.ok) return
const { data } = await response.json()
// Oldest first, so handlers see events in the order they were filed.
for (const event of data.reverse()) handle(event)
}
async function listen() {
const response = await fetch(STREAM, {
headers: { Authorization: `Bearer ${KEY}` },
})
if (!response.ok) throw new Error(`stream refused: ${response.status}`)
const reader = response.body.pipeThrough(new TextDecoderStream()).getReader()
let buffer = ""
for (;;) {
const { value, done } = await reader.read()
if (done) return
buffer += value
// SSE messages are separated by a blank line.
let split
while ((split = buffer.indexOf("\n\n")) !== -1) {
const message = buffer.slice(0, split)
buffer = buffer.slice(split + 2)
// Lines starting with a colon are comments - the keepalive.
const payload = message
.split("\n")
.filter((line) => line.startsWith("data:"))
.map((line) => line.slice(5).trim())
.join("")
if (payload) handle(JSON.parse(payload))
}
}
}
function handle(event) {
if (seen.has(event.filing_id)) return
seen.add(event.filing_id)
console.log(event.filed_at, event.ticker, event.event_type, event.title)
}
// Reconnect with a growing delay, and cover the gap before listening again.
let delay = 1000
for (;;) {
try {
await catchUp(15)
delay = 1000
await listen()
} catch (cause) {
console.warn("stream interrupted:", cause.message)
}
await new Promise((resolve) => setTimeout(resolve, delay))
delay = Math.min(delay * 2, 60000)
}Cluster-buy stream
The second stream announces the moment a newly filed insider buy lifts a company to your threshold of distinct buyers. It takes the same parameters as the cluster-buy endpoint: min_insiders (default 3), window (default 7d, on the transaction date) and roles, plus ticker for a single company. This example only counts officers and directors:
curl --no-buffer -H "Authorization: Bearer $ALGOUM_API_KEY" \
"https://api.algoum.de/v1/insider/cluster-buys/stream?min_insiders=3&roles=officer,director"Every message uses the event name cluster_buy and carries the same cluster object the cluster-buy endpoint returns, including the filings behind it in evidence. The keepalive is the same as above.
event: cluster_buy
data: {"ticker":"XYZ","cik":"0001234567","insider_count":3,"total_shares":21500,"total_value":{"amount":452150,"currency":"USD"},"window":"7d","as_of":null,"roles":["director","officer"],"first_buy_date":"2026-07-09","last_buy_date":"2026-07-13","min_insiders":3,"uniform_price":false,"rule_version":"cluster-buys-v1","sec_known_at":"2026-07-14T16:05:00-04:00","evidence":[{"filing_id":"0001234567-26-000101","insider_name":"Example Insider A","role":"officer","reporting_owners":[],"filed_at":"2026-07-10T17:12:00-04:00","source_url":"https://www.sec.gov/Archives/edgar/data/1234567/..."},{"filing_id":"0001234567-26-000102","insider_name":"Example Insider B","role":"director","reporting_owners":[],"filed_at":"2026-07-13T09:41:00-04:00","source_url":"https://www.sec.gov/Archives/edgar/data/1234567/..."},{"filing_id":"0001234567-26-000103","insider_name":"Example Insider C","role":"director","reporting_owners":[],"filed_at":"2026-07-14T16:05:00-04:00","source_url":"https://www.sec.gov/Archives/edgar/data/1234567/..."}]}
A message arrives once, when the threshold is crossed. Nothing is sent for:
- clusters that already existed when the stream service started,
- further buys into a cluster that is already above the threshold,
- a cluster dropping out of the window again,
- older filings that are loaded later.
Catch up the same way as with events: on start and after every reconnect, read /insider/cluster-buys with the same parameters, then keep listening. A company from the catch-up can show up on the stream as well; de-duplicate on ticker. We have not measured the delivery time of this stream yet, so there is no figure here; record your own receipt time if you need one. A message is a data signal, not a trading recommendation, and says nothing about prices or fills.
When the stream is unavailable
If the stream is not running, the endpoint answers 503 with the code stream_unavailable instead of holding a connection open that would never deliver anything. That is a temporary state — retry, and use /events/recent or /insider/cluster-buys in the meantime.