How to stream news in real time with SSE#

To stream news in real time, open a single persistent connection to GET /v1/news/stream. APITube keeps it open and pushes each new article that matches your filters as a Server-Sent Events (SSE) message — you never poll. The fastest way to try it is one cURL command:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?language.code=en"

The -N flag turns off cURL buffering so events print the instant they arrive. The connection stays open and new English-language articles appear as they are published. Pass your key either in the X-API-Key header or as an ?api_key= query parameter.

How does the SSE stream work?#

The stream checks for new matching articles roughly every 30 seconds and sends up to 50 articles per cycle. Between articles, APITube sends a heartbeat comment about every 30 seconds to keep the connection alive — these heartbeats are free and not real events. A single connection can stay open for up to 6 hours, after which the server asks you to reconnect (it sends error code ER0362).

Crucially, the stream is for new articles, not a history dump. When you connect without a resume header, APITube anchors to the latest matching article and then streams everything published after that moment. To pull older articles, run a normal search against the /everything endpoint instead.

What does an SSE message look like?#

Each delivered article arrives as a named article event with a unique id: and the full article JSON on data: lines:

event: article
id: 123456
data: {"id":123456,"title":"...","source":{"domain":"reuters.com"},...}

The data: payload is the same article object you get from a news search, so any code that already parses /everything results works unchanged. The id: is the article ID — keep the latest one you received, because it is your resume point. Error conditions arrive as an error event, for example event: error with data: {"code":"ER0301","message":"Balance exhausted"}, after which the server closes the connection.

How do I filter what the stream sends?#

Every filter that works on a normal news search works here — append it to the query string. Language, category, source, sentiment, entities, sorting, and field selection all apply:

# English sport news from one source, only the fields you need
curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?language.code=en&category.id=medtop:15000000&source.domain=reuters.com&fl=id,title,source.domain"

Use the fl parameter to trim each message to just the fields you use — see how to select specific response fields — and start narrow with a filter like language so you only pay for articles you actually want. The official SSE Stream reference on docs.apitube.io lists every supported language and client snippet.

How do I reconnect without losing articles?#

SSE has built-in resume. Every article event carries an id:; if the connection drops, reconnect and send the last ID you saw in the Last-Event-Id request header:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  -H "Last-Event-Id: 123456" \
  "https://api.apitube.io/v1/news/stream?language.code=en"

APITube immediately delivers any matching article published after ID 123456, then continues streaming new ones — so a brief network blip costs you nothing. In the browser, the native EventSource API does this for you: it reconnects automatically and replays the last event ID with no extra code.

What does streaming cost?#

You are billed 1 credit per article actually delivered — never for the open connection and never for heartbeats. Credits are deducted as each article is written to you, so if nothing matches your filters, nothing is spent. Streaming draws from a separate streaming-credit pool on your account, distinct from your regular request credits; when that pool is empty, a positive pay-as-you-go balance is used instead.

If you connect with no streaming credits and no paid balance, the server rejects the connection with HTTP 402 and code ER0176. If the balance runs out mid-stream, you get an error event with code ER0301 and the connection closes — reconnect after topping up or when your plan credits renew.

Common Questions#

• How is SSE different from webhooks?
• How many streams can I run at once?
• Can I open the stream from a browser?
• Do test keys work with the stream?

How is SSE different from webhooks?#

SSE keeps a connection you hold open and pushes articles down it in real time, which suits live dashboards and a process that runs continuously. A webhook instead has APITube POST new articles to a URL you registered, which suits server-to-server alerting where you do not want to babysit a socket. Both deliver the same article objects and both bill per delivered article; pick SSE when your client is long-lived, and a webhook when you want delivery to your endpoint without an always-on connection.

How many streams can I run at once?#

The number of simultaneous SSE connections depends on your plan. Streaming is not available on the Free plan; paid plans allow 2 simultaneous connections on Basic, 10 on Professional, and 50 on Corporate. Opening one more than your plan allows returns HTTP 429 with code ER0360. Closing a stream frees its slot, so close connections you no longer need rather than leaving them idle.

Can I open the stream from a browser?#

Yes, with the standard EventSource API. Because browsers cannot set custom headers on an EventSource, pass your key as a query parameter: new EventSource('https://api.apitube.io/v1/news/stream?api_key=YOUR_API_KEY&language.code=en'). Listen for the article event and parse event.data. Keep in mind the key is then visible in the page, so use a restricted key for browser-side code rather than a privileged one.

Do test keys work with the stream?#

Yes. A test key streams live events but the article content is masked for preview, and deliveries do not consume your quota. Use a test key to confirm your client connects, parses the article event format and handles reconnection, then switch to a live key to receive full article content and real-time delivery.