How streaming (SSE) quota is counted#

The SSE stream at /v1/news/stream bills one credit per article it actually delivers to you — never for the open connection, and never for heartbeats. Those credits come from a separate streaming pool on your account (the API tracks it as sse_points), distinct from the request quota that your normal searches draw down. So an open stream that matches nothing costs nothing, and your regular search quota is untouched by streaming.

This is the key difference from a normal call. A search like /v1/news/everything costs one credit per call regardless of how many articles come back. Streaming flips that: there is no per-call charge, only a per-article charge, counted as each article is written to your connection.

What exactly gets billed on an SSE stream?#

Only a successfully delivered article is billed, and the charge is one credit drawn from your streaming pool for each one. Concretely:

• Each delivered article = 1 streaming credit. The stream checks for new matching articles about every 30 seconds and pushes up to 50 per cycle; every article written to your socket deducts one streaming credit and is logged as a stream request.
• The open connection is free. Holding /v1/news/stream open costs nothing on its own — you are not charged for connection time.
• Heartbeats are free. About every 30 seconds the server sends a : heartbeat comment to keep the connection alive. These are not events and are never billed.
• The last, undelivered frame is free. If your client drops mid-write and the final article never flushes, that article is not charged — the credit is only taken once the article is confirmed written.

Because billing is per article, the way to control streaming spend is to filter tightly. Every search filter works on the stream, so narrowing by language.code, category.id, source.domain or sentiment means fewer matching articles, which means fewer credits. See how to stream news in real time with SSE for the filtering syntax.

Does the streaming pool share my search quota?#

No. Streaming has its own pool. Your account carries three separate allowances that do not borrow from each other:

• Request pool — drawn down by normal REST calls like /v1/news/everything (one credit per call).
• Streaming (SSE) pool — drawn down only by /v1/news/stream, one credit per delivered article.
• WebSocket pool — drawn down only by the /v1/news/ws stream, also one credit per delivered article.

Spending your monthly search quota does not stop you from streaming, and a busy stream does not eat into the budget for your searches. Each pool is counted independently. (For how the request pool is charged on regular calls, see what counts as one request.)

What happens when the streaming pool runs out?#

It depends on whether you have a pay-as-you-go balance:

• No streaming credits and no balance, at connect time — the server refuses the connection with HTTP 402 and code ER0176 (“You have no SSE points on your account.”). Top up or wait for your renewal, then reconnect.
• Streaming pool empties mid-stream, no balance — you receive an error event with code ER0301 (“Balance exhausted”) and the connection closes. Reconnect once your pool refills or after you add funds.
• Paid plan with a pay-as-you-go balance — when the streaming pool reaches zero, delivery does not stop. Each further article falls back to your balance at $0.01 per article (one cent), the same pay-as-you-go rate as regular requests. Streaming keeps flowing past the pool until the balance runs out.

If you have set a monthly pay-as-you-go spending limit and reach it while streaming on balance, the stream stops with 402 ER0177 (“Monthly pay-as-you-go spending limit reached”) instead — that cap resets at the start of each calendar month. For the general overflow behaviour, see what happens when you run out of requests.

How do connection limits affect what I spend?#

Streaming is not available on the Free plan; paid plans cap concurrent SSE connections at 2 on Basic, 10 on Professional, and 50 on Corporate. Opening one more than your plan allows returns HTTP 429 with code ER0360. These limits cap concurrency, not cost — every connection still bills per delivered article from the same shared streaming pool, so two open streams that both match the same articles will each be billed for the articles they receive. Close streams you no longer need so an idle connection does not hold a slot.

A single connection also has a 6-hour lifetime; after that the server sends error ER0362 and asks you to reconnect. Reconnecting with the Last-Event-Id header resumes from your last article without gaps and without re-billing articles you already received.

Common Questions#

Why did my streaming pool drop while I made no searches?#

Because streaming and searching are billed from different pools. Every article the SSE stream pushed to you deducted one streaming credit, even though you ran no /v1/news/everything calls. Each delivery is recorded as a stream request in your logs, so open your request logs to see exactly which articles were billed and when.

Do test keys consume streaming quota?#

No. A test key streams live events but its article content is masked for preview, and deliveries do not draw down any pool — streaming or otherwise. Use a test key to confirm your client connects, parses the article event and handles reconnection, then switch to a live key for full content and real billing.

Can I check my streaming pool with /v1/balance?#

Not directly — the /v1/balance endpoint returns your request points and plan, not the streaming pool. To see streaming spend, look at your request logs (each delivered article appears as a stream request) or the usage view in your dashboard, where streaming deliveries are counted alongside your other traffic.

Is the open connection or heartbeat ever billed?#

No. You are billed strictly per article delivered. The persistent connection itself, the periodic : heartbeat keep-alives, and any final article that fails to flush before a disconnect are all free. If your filters match nothing for an hour, that hour of streaming costs zero credits.