no key · no human
Home › API documentation › GET /v1/stats

GET /v1/stats

The shape of a slice instead of its contents. Same filters as /v1/search, but the response is counts, not articles.

bash
curl "https://freenewsapi.ai/v1/stats?q=wildfire&date=7d&top=10"
response
{
  "took_ms": 88,
  "total": 3417,
  "countries": { "US": 812, "AU": 604, "GR": 331, "ES": 288, "CA": 190 },
  "languages": { "en": 1902, "es": 411, "el": 331, "fr": 208 },
  "tlds":      { "com": 1744, "au": 402, "gr": 288, "es": 201 },
  "hosts":     { "www.abc.net.au": 121, "www.theguardian.com": 96 },
  "by_day":    { "2026-08-17": 611, "2026-08-16": 588, "2026-08-15": 502 }
}

Parameters

Accepts q, country, lang, tld, host, date, from, to and strict_country — identical in meaning to /v1/search. Plus one of its own:

topinteger 1–100default 20

How many buckets to return per facet. Facets are ordered by count, descending.

Response

  • total — exact number of matching articles. Unlike /v1/search, this is never capped.
  • countries, languages, tlds, hosts — maps of key to count, ordered by count.
  • by_day — article count per calendar day, newest first, days with zero articles omitted.

Facet counts are computed over the whole matching set, not over the current page, so they are stable regardless of size or offset. Aggregations are heavier than a plain search — expect 80–200 ms rather than 40.

What it is good for

Four questions this answers that a search cannot answer cheaply:

  • Is there a story here? A topic with 4 articles from 2 publishers is not an event. One with 300 articles from 90 publishers is.
  • Where is it being covered? The country and language breakdown shows whether a story is global or confined to one press. That is frequently the more interesting finding.
  • When did it start? by_day gives the shape of the coverage over the retention window — a sudden spike, a slow build, or a steady background hum.
  • Who is driving it? If one publisher accounts for most of the volume, you are looking at one outlet's campaign rather than broad coverage. Counting distinct hosts measures independent sources; counting articles measures syndication.

Use it to decide before you read

The efficient pattern for an agent: aggregate first to learn where the story is, then search only the slice that matters. One /v1/stats call replaces a dozen exploratory searches.

bash
# where is this story being covered?\ncurl "https://freenewsapi.ai/v1/stats?q=export+ban&date=48h"\n\n# it is mostly Indian coverage \u2014 now read those\ncurl "https://freenewsapi.ai/v1/search?q=export+ban&country=IN&date=48h&size=20"

Corpus overview, no filters

bash
curl "https://freenewsapi.ai/v1/stats?top=100"

That call powers the live statistics page.