How to aggregate news results with facets#

The APITube News API facet parameter returns grouped counts of matching articles instead of (or alongside) the articles themselves. Set facet=true and list the fields you want to group by in facet.field — for example facet.field=source.id,language.id — and the response gains a facets object with the count of articles per value. This is how you build filtered navigation, analytics dashboards, and distribution charts without downloading and counting articles yourself.

curl "https://api.apitube.io/v1/news/everything?title=tesla&facet=true&facet.field=source.id,language.id&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. Faceting runs inside the same search request — you do not call a separate endpoint for it.

How does the facet parameter work?#

Faceting is enabled with facet=true (or facet=1). When it is on, facet.field is required and takes a comma-separated list of up to 5 fields. The API groups every article that matches your filters by each listed field and returns the count per value. The grouping uses the same WHERE conditions as your search, so facet counts always reflect the filters you applied — a source filter, a date range, a keyword, and so on.

Counts are computed across the full matching set, not just the page you requested. Your page and per_page values shape the results array, but the facet counts ignore pagination and report the totals for everything that matches.

The response adds a facets object keyed by each field name. Each entry is an array of { value, count } pairs:

{
  "status": "ok",
  "results": [...],
  "facets": {
    "source.id": [
      { "value": 12345, "count": 150 },
      { "value": 12346, "count": 120 }
    ],
    "language.id": [
      { "value": 1, "count": 450 },
      { "value": 2, "count": 120 }
    ]
  }
}

Which fields can I facet on?#

You can group by many article attributes. Common choices include:

• Source and language: source.id, source.country.id, source.bias, source.rank.opr, language.id, author.id
• Classification: category.id, topic.id, industry.id, entity.id
• Sentiment: sentiment.overall.polarity, sentiment.title.polarity, sentiment.body.polarity, sentiment.strength
• Article attributes: is_duplicate, is_free, is_important, read_time, content.length, media.images.count, media.videos.count
• Time: published.year, published.month, published.day_of_week, published.hour, published.weekday, published.time_of_day

Faceting on entity.id is a fast way to find the most-mentioned people, companies and brands inside a result set — useful when you want to know who a topic is about, which pairs well with finding news by entity.

curl "https://api.apitube.io/v1/news/everything?topic.id=business&facet=true&facet.field=entity.id,sentiment.overall.polarity&api_key=YOUR_API_KEY"

How to control how many facet values come back#

Two optional parameters shape the lists:

• facet.limit — the maximum number of values returned per field. Default is 10, and the cap is 100.
• facet.mincount — the minimum count a value needs to appear. Default is 1, so by default every value with at least one article is included.

For most fields the values are ordered by count, highest first, so the top entries are the largest groups. Time-based and computed fields (such as published.year or content.length) are ordered by their value instead.

curl "https://api.apitube.io/v1/news/everything?facet=true&facet.field=source.id&facet.limit=20&facet.mincount=5&api_key=YOUR_API_KEY"

How to facet over ranges (dates and numbers)#

Beyond grouping by exact values, you can bucket a numeric or date field into ranges with facet.range=true. Set facet.range.field to the field, and provide facet.range.start and facet.range.end (both required). The optional facet.range.gap sets the bucket size and defaults to +1DAY for dates. Range fields include published_at, read_time, source.rank.opr, media.images.count, media.videos.count, and the sentiment score fields (sentiment.overall.score, sentiment.title.score, sentiment.body.score).

curl "https://api.apitube.io/v1/news/everything?facet.range=true&facet.range.field=published_at&facet.range.start=2026-06-01&facet.range.end=2026-06-26&facet.range.gap=+1DAY&api_key=YOUR_API_KEY"

Range results arrive under a key named <field>_ranges (for example published_at_ranges), where each bucket is { range_start, range_end, count }. This is the building block for a “articles per day” volume chart.

Common Questions#

Which endpoints support faceting?#

Faceting works on the article-search endpoints: /v1/news/everything, /v1/news/top-headlines, /v1/news/story, /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity. The parameters behave the same on each one.

Can I get only the counts without the articles?#

The facets object is returned alongside the normal results array. To keep the response small while you build a dashboard, combine faceting with a tiny page (per_page=1) and field selection — see returning only specific fields with fl. The facet counts still cover the full matching set regardless of how small the page is.

What errors can faceting return?#

All faceting errors are 400 responses. ER0310 is returned when facet=true but facet.field is missing. ER0312 is returned when facet.field lists more than 5 fields. ER0313 is returned when a field name is not supported, and the message lists every allowed field. For range faceting, ER0332 is returned when facet.range.start or facet.range.end is missing. Check field names against the official News API parameters reference before sending the request.

Why don’t my facet counts match the number of results?#

They are measuring different things. The results array is limited by your page and per_page values, while facet counts are computed over every article that matches your filters. A request that returns 25 articles on the page can still report thousands across its facet values — that is expected.