algoumfinancial data, made clear
♥Donate
HomeWhy?LiveDocumentationResearchAbout♥Donate

Documentation

OverviewGetting startedConventionsEndpoint referenceStreamsData sourcesMethodologyAI assistants (MCP)Pricing and limitsChangelog

Tools

Swagger UIOpenAPI file
algoum is a data service — not investment advice.
DonateContactPricingChangelogLegal NoticeTerms and ConditionsPrivacy PolicyDisclaimer

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

text/event-stream
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
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:

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

text/event-stream
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.