Quickstart

No account to create, no key to paste. Copy the line, run it, read JSON.

1. Search

curl "https://freenewsapi.ai/v1/search?q=climate+summit&size=2"

{
  "took_ms": 41,
  "total": 1284,
  "total_is_lower_bound": false,
  "size": 2,
  "offset": 0,
  "results": [
    {
      "id": "9c1f8a4b2d3e5f6071829304a5b6c7d8",
      "url": "https://example-news.com/world/climate-summit-opens",
      "title": "Climate summit opens with a call for binding targets",
      "description": "Delegates from 190 countries gathered on Monday ...",
      "published_at": "2026-08-17T09:12:00Z",
      "crawled_at": "2026-08-17T10:48:31Z",
      "host": "example-news.com",
      "sitename": "Example News",
      "country": "GB",
      "country_source": "cctld",
      "lang": "en",
      "tld": "com"
    }
  ]
}

Three fields in that response are worth noticing straight away. total is how many articles matched, not how many were returned — it is capped at 10,000 for speed, and total_is_lower_bound tells you when you hit the cap. country_source says how the country was determined, which matters because roughly a third of country values in any news dataset are inferences rather than facts. And crawled_at is the honest timestamp: publishers can backdate published_at, but crawl time is assigned by the pipeline.

2. Narrow it down

Filters combine with AND across parameters and OR within one. So country=DE,AT&lang=de reads as "German-language articles from Germany or Austria". This asks for today's Ukrainian-language articles from Ukraine, newest first:

curl "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"

3. Get the full text

Search results omit the article body by default to keep responses small. Ask for it explicitly when you have picked the articles you actually want:

curl "https://freenewsapi.ai/v1/search?q=inflation&full_text=true&size=5"

4. Count instead of listing

Often the useful question is not "what are the articles" but "is there anything here at all, and where is it". Counting answers that for a fraction of the cost — about 200 tokens against several thousand for a page of results — which makes it the right first call for an agent deciding whether a search is worth running:

curl "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"

The response gives you counts by country, language, domain zone, publisher and day, computed over the whole matching set rather than the current page.

In Python

import requests

r = requests.get("https://freenewsapi.ai/v1/search", params={
    "q": "semiconductor export controls",
    "date": "7d",
    "lang": "en",
    "size": 20,
    "sort": "relevance",
})
for a in r.json()["results"]:
    print(a["published_at"], a["host"], a["title"])

In JavaScript

const url = new URL("https://freenewsapi.ai/v1/search");
url.search = new URLSearchParams({ q: "central bank", date: "24h", size: "20" });

const { results } = await (await fetch(url)).json();
results.forEach(a => console.log(a.published_at, a.host, a.title));

Next