How to receive instant breaking-news alerts#

To get breaking news the instant it is published, open one Server-Sent Events connection to GET /v1/news/stream and add is_breaking=1. APITube holds the connection open and pushes only articles flagged as breaking — you never poll a search endpoint. A single cURL command is enough to start:

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

The -N flag disables cURL buffering so each alert prints the moment it arrives. The is_breaking=1 filter runs through the same filter chain as a normal search, so the live feed carries only breaking stories. You can pass your key as the X-API-Key header or as an ?api_key= query parameter.

What does an instant breaking-news alert look like?#

Each breaking article is pushed as a named article event with a unique id: and the full article JSON on data: lines — the same object you get from a search:

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

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

The stream delivers new breaking articles only, not a backlog. On connect, APITube anchors to the latest matching article and then pushes everything published after that moment, so you receive each story as it breaks rather than a history dump.

How do I scope alerts to a topic, language or place?#

Because is_breaking lives in the shared filter chain, it stacks with every other search filter using AND logic — append them to the same query string. This narrows the live feed to English breaking news from one source and trims each message to a few fields:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?is_breaking=1&language.code=en&source.domain=reuters.com&fl=id,title,published_at"

To watch breaking events around a single place, layer a geographic radius on top — here, within 100 km of central London:

curl -N -H "X-API-Key: YOUR_API_KEY" \
  "https://api.apitube.io/v1/news/stream?is_breaking=1&location.lat=51.5074&location.lng=-0.1278&location.radius=100"

is_breaking accepts only 0 or 1: a non-numeric value is rejected with 400 and code ER0185, and any other number returns 400 with ER0186. For the full breaking filter and how it behaves on search, see how to monitor breaking news and real-time events.

How do I reconnect without missing an alert?#

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?is_breaking=1"

APITube delivers any matching article published after id 123456, then keeps streaming, so a brief network blip costs you no alerts. In the browser, the native EventSource API replays the last id for you automatically. For the full SSE mechanics, see how to stream news in real time with SSE.

What does a breaking-news stream cost?#

You are billed one credit per breaking article actually delivered — never for the open connection and never for heartbeats. If nothing breaks that matches your filters, nothing is spent. Streaming draws from a separate streaming-credit pool on your account; 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 402 and code ER0176. If the balance runs out mid-stream, you get an error event with code ER0301 and the connection closes — top up or wait for your plan credits to renew, then reconnect.

Common Questions#

• How many breaking-news streams can I run at once?
• Does is_breaking=1 mean the story is only minutes old?
• Can I test breaking alerts without spending credits?
• Should I use a stream or a webhook for alerts?

How many breaking-news 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 429 with code ER0360. Closing a stream frees its slot, so close connections you no longer need rather than leaving them idle.

Does is_breaking=1 mean the story is only minutes old?#

No. is_breaking=1 filters by the breaking flag the pipeline assigns to an article, not by a time window. The stream itself only ever delivers articles published after you connect, so on the live feed every alert is genuinely new — but the flag alone is not a freshness guarantee on a normal search.

Can I test breaking alerts without spending credits?#

Yes. A test key streams live article 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 for full content and real billing.

Should I use a stream or a webhook for alerts?#

Use the SSE stream when your client is long-lived and holds the connection open — a live dashboard or an alerting process that runs continuously. Use a webhook when you want APITube to push alerts to your endpoint without keeping a socket open. Both deliver the same article objects and both bill per delivered article; for a side-by-side guide, see SSE vs WebSocket vs webhooks: which to choose.