How to monitor breaking news and real-time events#

To keep only articles flagged as breaking news, add is_breaking=1 to a search request. It is a flag that accepts exactly 0 or 1, and on its own it returns the newest breaking stories first. This request pulls current breaking news:

curl "https://api.apitube.io/v1/news/everything?is_breaking=1&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. Without this flag, no breaking filter is applied and breaking and regular articles come back together.

What does is_breaking do?#

is_breaking=1 matches only articles that the pipeline marked as breaking or important; is_breaking=0 returns only the regular ones. The flag accepts nothing but 0 or 1. A non-numeric value is rejected with a 400 error and code ER0185, and any other number returns 400 with code ER0186 and the message that is_breaking must be 0 or 1.

Every article in the response carries an is_breaking field set to true or false, so you can confirm the flag on each result and use it in your own logic even when you did not filter on it.

How to get the freshest breaking news first#

The default sort order is by publish time, newest first, so a plain is_breaking=1 already returns the most recent breaking stories at the top. You can make that explicit, or pick a different ranking. This request keeps the breaking filter and sorts by publish time descending, returning only a few compact fields:

curl "https://api.apitube.io/v1/news/everything?fl=id,title,source.domain,published_at&is_breaking=1&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

To rank breaking stories by social traction instead of recency, sort by engagement. This pattern surfaces the breaking articles that are spreading fastest:

curl "https://api.apitube.io/v1/news/everything?is_breaking=1&media.images.count.min=2&sort.by=engagement&sort.order=desc&api_key=YOUR_API_KEY"

How to stream breaking news in real time#

Filtering returns what already exists. To receive breaking articles the moment they are published, open the Server-Sent Events stream at /v1/news/stream with the same parameters. The stream runs the same filter chain, so is_breaking=1 narrows the live feed exactly as it does on search:

curl -N "https://api.apitube.io/v1/news/stream?is_breaking=1&api_key=YOUR_API_KEY"

The connection polls for new matching articles every 30 seconds and sends a heartbeat every 30 seconds to keep the socket open. Each delivered article counts as one request against your stream quota. If the connection drops, reconnect with the Last-Event-Id header set to the id of the last article you received, and the stream resumes after that point instead of replaying everything.

How to track regional breaking events#

Because is_breaking belongs to the shared filter chain, it stacks with every other filter using AND logic. Pair it with a geographic radius to watch breaking news around one place — here, within 100 km of central London:

curl "https://api.apitube.io/v1/news/everything?location.lat=51.5074&location.lng=-0.1278&location.radius=100&is_breaking=1&api_key=YOUR_API_KEY"

You can layer language, category, source or any other filter on top. For the full geo syntax, see How to find news near a coordinate or bounding box. Every parameter used here is listed in the official News API parameters reference.

Which endpoints support the breaking filter?#

is_breaking works the same way across the shared filter chain — including /v1/news/everything, /v1/news/count and the /v1/news/stream SSE feed. Because /v1/news/count runs the same chain, you can count how many breaking articles match without downloading them by sending is_breaking=1 to that endpoint. The /v1/news/top-headlines endpoint is a related shortcut: it already returns only important articles from high-ranked sources, so reach for Top Headlines when you want a curated breaking feed without building the filter yourself.

Common Questions#

• Does is_breaking=1 guarantee the story is from the last few minutes?
• What value other than 0 or 1 can I pass?
• How is streaming different from polling search?
• Why use top-headlines instead of is_breaking?

Does is_breaking=1 guarantee the story is from the last few minutes?#

No. is_breaking=1 filters by the breaking flag the pipeline assigns, not by a time window. To bound recency, combine it with a date filter or sort by published_at descending so the newest breaking articles sit at the top.

What value other than 0 or 1 can I pass?#

None. is_breaking accepts only 0 or 1. A non-numeric value returns 400 with code ER0185, and any other number returns 400 with code ER0186 stating the flag must be 0 or 1.

How is streaming different from polling search?#

Search returns articles that already match at request time. The /v1/news/stream SSE endpoint keeps the connection open and delivers new matching articles as they are published, polling every 30 seconds with a heartbeat every 30 seconds, and each delivered article counts against your stream quota.

Why use top-headlines instead of is_breaking?#

/v1/news/top-headlines already restricts results to important articles from high-ranked sources, so it is a ready-made breaking feed. Use is_breaking=1 on /v1/news/everything when you want full control over the rest of the filter chain.