What counts as one request?#

One request is one billed API call, and most calls cost one credit drawn from your account quota. A standard search or retrieval call — /v1/news/everything, /v1/news/top-headlines, /v1/news/article, /v1/news/count and similar endpoints — deducts a single credit. A few endpoints cost more, and a few cost nothing, so it pays to know which is which before you build.

Credits (the API also calls them points) are your plan’s request allowance for the period. Each billed call draws one credit from the pool, the dashboard counts it, and when the pool hits zero the API stops serving paid endpoints until your quota resets or you top up.

How many credits does each endpoint cost?#

Pricing is per call, not per article returned. The defaults:

• Standard search and retrieval — 1 credit. /v1/news/everything, /v1/news/top-headlines, /v1/news/article, /v1/news/story/:id, /v1/news/count, the category/topic/industry/entity feeds, /v1/news/trends, /v1/news/raw, and people/company directory lookups each cost one credit.
• Local news — 1 credit plus 1 per insight. /v1/news/local charges one credit for the listing and one more for each insight block you ask it to compute, so a request that bundles several insights costs more than one.
• Fact-check — 5 credits. /v1/fact-check is the most expensive single call, charging five credits because it runs a retrieval-and-reasoning pass over the matching coverage.
• Streaming — 1 credit per article delivered. The real-time SSE stream (/v1/news/stream) bills per article it pushes to you, not per connection, and it draws from a separate streaming pool rather than your standard request quota.

A single response can return up to 250 articles (the per_page maximum), and that whole page still costs one credit on the search endpoints — page size does not change the price.

Does an empty search still cost a credit?#

No. The article-returning search endpoints only charge when they actually return at least one article. If /v1/news/everything, /v1/news/top-headlines, /v1/news/article or the category/topic feeds match nothing, the call returns an empty result set and no credit is deducted. This means a tightly filtered query that comes back empty is free to retry after you loosen the filters.

The one exception is /v1/news/count, which always returns a number and therefore always costs one credit, even when that number is zero. So if you only need to know how many articles match, expect to pay for the count call regardless of the result.

Which calls cost nothing?#

Two things never draw down your quota:

• Checking your balance. /v1/balance returns your remaining credits and plan without charging anything, so you can poll it freely. See how to check your balance via the API.
• Test-key requests. Calls made with a test key (or in the dashboard’s Test mode) hit the live API but do not consume quota — they are for previewing shapes and responses, not billed traffic.

Requests that are rejected before they run are also not billed: an invalid key (401), an exhausted quota (402 ER0176), or a rate-limit block (429) is turned away before any credit is charged.

How are credits drawn — quota or balance?#

Your plan quota is spent first; only once your monthly quota is used up does an eligible call fall back to your pay-as-you-go balance instead of failing — so a request still counts as one charge, just against a different pool. Every billed call also writes a log line and bumps the calling key’s lifetime usage total, which is how the dashboard attributes spend per key.

Common Questions#

Does returning more articles cost more credits?#

No. On the search endpoints the price is one credit per call, whether the page holds one article or the full 250-article maximum. To pull large result sets economically, raise per_page and paginate rather than making many small calls — fewer calls means fewer credits.

Is /v1/news/count really billed even when it returns zero?#

Yes. Unlike the article-returning endpoints, /v1/news/count charges one credit on every call because it always produces a result — the count itself. Use it when you specifically need a total; if you just want to check whether any articles exist, a normal search that returns nothing is free.

Why did my usage go up without a successful search?#

Most likely a /v1/news/count call or a streamed article. Count requests bill regardless of the number returned, and the SSE stream bills one credit for each article it delivers. To see exactly what was charged and when, open your request logs or track your usage and quota in the dashboard.

How do I see what I’ve spent per key?#

Open a key’s detail page in the dashboard for a lifetime usage-points total plus a date-range breakdown of requests, cost and top endpoints. See how to view usage for each API key — useful for spotting which key drives the most spend.