How to count matching articles without downloading them#

To get just the number of articles matching your filters — without loading any content — call the /v1/news/count endpoint. It accepts the same filters as the main search but runs a single count(*) query, so it is cheaper and faster when all you need is the total. This counts English articles published in the last 7 days:

curl "https://api.apitube.io/v1/news/count?language.code=en&published_at.start=NOW-7DAYS&api_key=YOUR_API_KEY"

You can pass the key as the api_key query parameter or as an X-API-Key header.

What does the count endpoint return?#

/v1/news/count returns a small JSON object with the total and a request id — never any article bodies:

{
  "status": "ok",
  "count": 12345,
  "request_id": "3a7e5d21-9c4b-4f8a-b2e1-6f0d9a3c5e88"
}

The count field is the number of articles that match the filters you sent, status is always ok on success, and request_id uniquely identifies the call. Because no content is loaded, the response stays tiny no matter how many articles match.

How to count articles matching your filters#

The endpoint supports every filter available on the main /v1/news/everything search — language, title, date range, category, source and the rest. Add the filters you would normally use for a search, and you get the count for exactly that result set.

You can call it with GET (filters as query parameters) or POST (filters as a JSON body); the two are equivalent. A POST example that counts English articles mentioning “climate change” in the title since the start of 2026:

curl -X POST "https://api.apitube.io/v1/news/count" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "climate change",
    "language.code": "en",
    "published_at.start": "2026-01-01"
  }'

Because the filters are identical to search, you can build a query in the search endpoints first, confirm it returns what you expect, then swap the path to /v1/news/count to get the total. For the full filter set, see the Searching & Filtering News section, including How to filter news by date range.

How much does a count request cost?#

Each /v1/news/count call costs 1 point — regardless of how large the matching count is. That fixed cost is what makes count attractive: estimating the size of a 2-million-article result set costs the same as estimating a 5-article one, and you never pay to transfer content you do not need.

When should you use count instead of search?#

Reach for /v1/news/count whenever you need a number, not the articles themselves:

• Dashboards and KPIs — show “articles mentioning your brand this week” without fetching them.
• Sample-size estimation — check how many results a query has before deciding whether to page through them.
• Progress bars and pagination planning — learn the total up front so you know how many pages to request.

If you need the actual articles, use the search endpoints instead; if you only need the tally, count is the cheaper, faster path.

Common Questions#

• Can I call count with POST?
• Why is my count capped at 100?
• Does the count include article content?
• What errors can count return?

Can I call count with POST?#

Yes. /v1/news/count accepts both GET and POST. With GET, pass filters as query parameters; with POST, send them as a JSON body and set Content-Type: application/json. Both methods run the same query and return the same response.

Why is my count capped at 100?#

If you are using a test key, the count is capped (it returns at most 100) so the key cannot reveal the true catalogue size. Switch to a live key to get the real number for your filters.

Does the count include article content?#

No. /v1/news/count runs a count-only query and returns just status, count and request_id. It never loads article titles, bodies or metadata, which is exactly why it is faster and lighter than a full search.

What errors can count return?#

Common errors mirror the rest of the API: ER0201/ER0202 (HTTP 401) when the API key is missing or invalid, ER0176 (HTTP 402) when your account has no points left, and ER0203 (HTTP 429) when you exceed the rate limit. Each error response includes the request_id to help you trace the call.