How to measure PR and media coverage#

To measure PR and media coverage, count how many articles mention your brand with the /v1/news/count endpoint, then break that total down by competitor, tone and time using the facet parameters. Counting is separate from reading: /v1/news/count returns just a number for your filters — no article bodies — so a coverage report is a handful of small, cheap calls rather than a full download. This counts every article mentioning Tesla in the last 30 days:

curl "https://api.apitube.io/v1/news/count?organization.name=Tesla&published_at.start=NOW-30DAYS&api_key=YOUR_API_KEY"

You can send the key as an X-API-Key: YOUR_API_KEY header instead of the api_key query parameter. The response is a small JSON object — the total, a status and a request id — and never any content:

{
  "status": "ok",
  "count": 12345,
  "request_id": "1b6e9c42-7a3d-4058-9f1e-5c2d8b4a6f30"
}

How do I measure total coverage volume?#

Total coverage volume is a single /v1/news/count call whose filters describe “coverage of my brand”. Use organization.name for a company, brand.name for a consumer brand, or the numeric entity.id to pin one exact entity — each matches only articles that actually mention it. Add a published_at.start window so the number is scoped to a reporting period; published_at.start and published_at.end are inclusive and accept relative values like NOW-30DAYS or NOW-7DAYS, so you never have to compute dates yourself.

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

Because /v1/news/count accepts every filter the search endpoints do, you can build the query on /v1/news/everything first, confirm the articles look right, then swap the path to /v1/news/count for the tally. Each count call costs 1 point regardless of how large the total is — estimating a two-million-article result set costs the same as a five-article one. See how to count news articles without downloading them for the full behaviour.

How do I measure share of voice against competitors?#

Share of voice is the fraction of coverage in your category that belongs to each brand. The simplest way is one count call per brand over the same window, then divide each total by the sum:

curl "https://api.apitube.io/v1/news/count?brand.name=Nike&published_at.start=NOW-30DAYS&api_key=YOUR_API_KEY"
curl "https://api.apitube.io/v1/news/count?brand.name=Adidas&published_at.start=NOW-30DAYS&api_key=YOUR_API_KEY"
curl "https://api.apitube.io/v1/news/count?brand.name=Puma&published_at.start=NOW-30DAYS&api_key=YOUR_API_KEY"

If you already know each brand’s numeric entity.id, you can get all the totals in one search request by faceting on entity.id. Filter the search to your set of brands (entity.id accepts up to three comma-separated IDs with OR logic) and ask the API to group the matching articles by entity — per_page=1 keeps the article payload tiny while the facet counts still cover the whole matching set:

curl "https://api.apitube.io/v1/news/everything?entity.id=314,42,88&facet=true&facet.field=entity.id&per_page=1&api_key=YOUR_API_KEY"

The response gains a facets object where entity.id is an array of { value, count } pairs — one row per brand, value being the entity ID and count the number of matching articles — sorted from most-covered to least. That single grouped call is your share-of-voice table.

How do I break coverage down by tone?#

Coverage tone tells you whether the mentions are favourable. Run the same count three times, adding sentiment.overall.polarity set to positive, negative and neutral in turn — the three totals are your positive/negative/neutral split for the period:

curl "https://api.apitube.io/v1/news/count?organization.name=Tesla&sentiment.overall.polarity=negative&published_at.start=NOW-30DAYS&api_key=YOUR_API_KEY"

sentiment.overall.polarity takes positive, negative or neutral. An unrecognized value is not rejected — it falls back to neutral — and only a value longer than 10 characters returns error ER0103 (an empty value is simply ignored). This is the tone of the article as a whole, which is not the same as the tone aimed specifically at your brand inside it. When you need sentiment directed at the company itself, use the entity-level filter entity.sentiment.polarity instead — see how to monitor news about a company or brand for that distinction.

How do I chart coverage volume over time?#

A coverage timeline — articles per day across the campaign — comes from range faceting. Set facet.range=true, point facet.range.field at published_at, and give a facet.range.start (inclusive) and facet.range.end (exclusive — the end date itself is not counted, so use the day after your last day); both are required, or the request returns ER0332. The optional facet.range.gap sets the bucket size and defaults to +1DAY:

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

The counts arrive under a key named published_at_ranges, where each bucket is { range_start, range_end, count } ordered oldest-first — exactly the shape you feed a “mentions per day” chart. Widen the gap to +1WEEK for a longer campaign. To see which outlets drive the coverage, facet on source.id instead: facet=true&facet.field=source.id&facet.limit=20 returns your top 20 sources by article count. The full field list and range options are in how to aggregate news results with facets and the official News API parameters reference.

Common Questions#

• Does building a coverage report cost a lot of credits?
• Why don’t the facet counts match the results array?
• Can I measure coverage on a test key?

Does building a coverage report cost a lot of credits?#

No. Each /v1/news/count call is a flat 1 point no matter how many articles match, and a faceted search is a single request that returns grouped counts instead of pages of content. A full report — one total, a share-of-voice comparison, a tone split and a timeline — is a small fixed number of calls, not a bulk export. Counting and faceting are the cheap path precisely because no article bodies are transferred.

Why don’t the facet counts match the results array?#

They measure 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 one article on the page (per_page=1) can still report thousands across its facet values — that is expected, and it is why you can keep the page tiny while the counts stay complete.

Can I measure coverage on a test key?#

Only roughly. On a test key, /v1/news/count caps the returned total at 100 so the key cannot reveal the true catalogue size, which makes real volume and share-of-voice numbers unusable. A test key also masks article content with an upgrade marker rather than returning full bodies. Switch to a live key for accurate coverage figures and real reporting numbers.