Skip to main content
The news endpoint returns a curated, ranked feed of recent headlines for a fixed topic. The topic in the URL path selects the feed, and no query is needed:
This is a fast path for “give me the latest on X” requests — one call in place of a search-then-fetch loop. Add q to filter a topic by keyword, or format to get markdown, RSS, an HTML widget or a ticker instead of JSON.

Topics

topic is a path segment: GET /api/v1/news/:topic. 27 topics are available. GET /api/v1/news returns the list (see topics index). An unknown topic returns 404 with the full list of valid slugs — see unknown topics below.

Parameters

extracts and content read text Andi has already stored for each article. Nothing is fetched live.

Formats

All formats show the same ranked articles. format only changes how they are returned. embed and ticker are made to load inside an <iframe> on any site. A browser cannot send a header from an <iframe>, so use a feed key in the link. With a full API key, fetch the HTML from your server with the x-api-key header and put it in your page. Both are billed on the stories they show, not on the size of the HTML.

Filtering with q

q narrows a topic to stories that match your keywords, then ranks them against your query:
  • q can be up to 200 characters. A longer value returns 400.
  • q works with every format. You can also send it as query.
  • With format=embed or format=ticker, the widget and the ticker show a relevance-ranked order. Like the other q responses, they carry no topic brief.
  • A q response carries no topic brief: aiSummary is absent and answer is empty, because the brief describes the whole topic, not your filtered view.
  • Use /api/v1/search when you want to search the whole web rather than one topic.

Topics index

GET /api/v1/news lists every topic. It needs an API key and is not billed. Add format=html for the same list as a page of ready links.
format=html returns the same list as a simple web page, grouped as Topics, Regions, Extended topics and Curated groups. Each row shows the 48-hour story count and links to the topic’s RSS feed, widget and ticker, plus its detailed brief where one exists. Three example links show how to search inside a topic. Open it with a feed key and every link already carries the key, so you can click a link or copy it into a dashboard, feed reader or website:
Only a feed key is ever put into a link. A full API key is never shown, and a full key in the address returns 403. Send a full key in the x-api-key header and the page shows links without a key. Any other or missing format returns the JSON above, unchanged.

Response

With format=json (the default), the response uses the same shape as /api/v1/search: title, results, metrics, and (when available) images and answer. A news array is always present.
results and news contain the same articles — only the order differs. Reach for results when you want the best headlines first, and news when you want a chronological feed.

Unknown topics

Requesting a topic that doesn’t exist returns 404 with every valid slug, so a client can discover the full list from a single failed call:

Errors

For format=embed and format=ticker, the 400, 404, 502 and 503 errors come back as a short HTML message, so they show inside the frame. 401, 402, and 429 follow the same patterns as the search endpoint — see error handling.

Pricing

News requests are charged under the same outcome-based rule as search and fetch: the cost of the ranking work when you send q, a charge for each story returned by what it carries, plus a per-token rate on the returned content, with no flat per-call fee. A story’s extracts come from text Andi already stored with the feed, so a story with extracts is charged at a lower level than a search result with extracts. Current rates are in the API Console. The charge is returned in metrics.cost_dollars, the same field the search and fetch endpoints use. See pricing for all endpoints. format=embed and format=ticker are billed on the stories they show, not on HTML size. The topics index is free. Cache hits are billed for the stories and tokens only (no search runs), and are marked cached: true in metrics, alongside cache_age_seconds — see metrics.

Freshness and caching

Topic pages come back at once. Each page is kept for a short time that depends on its feed: from about 3 minutes for a busy topic to about 15 for a slow one, based on how often the feed gets new stories. Past that time, the page is rebuilt before it is returned. Just before then, it is returned at once and refreshed in the background. Each reply tells you how fresh it is: Send the ETag back as If-None-Match, or the Last-Modified value as If-Modified-Since. If the page has not changed, you get 304 Not Modified with no body and no charge. Replies that include page text (extracts or content) carry an ETag that also covers that text, and no Last-Modified. Send it back as If-None-Match: when neither the stories nor their text changed, you get 304 Not Modified with no charge. For these replies If-Modified-Since alone never returns 304. To poll a feed cheaply, send If-None-Match with the last ETag and since with the time of your last poll. An unchanged page is a free 304, and a changed one returns mostly stories that are new to you.

Dashboards, iframes and feed readers

A dashboard, a web page or a feed reader cannot send an x-api-key header. For these, use a feed key. A feed key is a key that only works for news feeds, so it is safe to put in a link.

Make a feed key

In the API Console, go to API Keys, choose Create Key, then Feed key. You can also open the News feeds page, which builds the link for you and shows a live preview. Add the key to the link as key:
What a feed key can do:
  • key in the URL works only for feed keys.
  • A feed key works only with format=rss, format=embed or format=ticker, and on the topics index.
  • With format=json, format=context or no format, a feed key gets 403. No format means json.
  • A feed key gets 403 on every other endpoint.
  • A full API key in a URL gets 403. Send a full key in the x-api-key header.

Ticker

format=ticker returns a single scrolling bar of headlines, for the top or bottom of a dashboard.

Search inside a widget or ticker

q (or query) works on every format. With q, the widget and the ticker show a relevance-ranked order of the matching stories. Both embed and ticker can be shown in an <iframe> on any site, and they reload themselves every 5 minutes.
  • Web page: use the <iframe> above. A ticker needs a height of about 48.
  • Grafana: in a News panel, paste the format=rss link into the URL field. The RSS feed can be read from the browser, across origins. In a Text panel, use the <iframe>. The Text panel needs disable_sanitize_html = true in your Grafana settings (self-hosted Grafana only).
  • Feed reader: use the format=rss link.
  • Sandboxed iframes: if you add a sandbox attribute, include allow-scripts. Without it, the widget does not reload by itself. The widget itself runs no scripts, and our security policy blocks any that are added.
Treat the link like a password. Anyone who has it can load that feed on your account. If it leaks, turn off or delete the feed key on the API Keys page.

Billing

Each load of the link is one call, billed on the stories shown. An open widget reloads every 5 minutes, which is about 290 calls a day.

Use cases

The news endpoint is built for fixed, recurring feed requests — the kind of thing a slash command or a scheduled agent job asks for repeatedly, like “latest world news” or “programming news.” Because the topic is fixed, there’s no query to construct and no need for a separate fetch pass to pull in full articles: one call returns a ranked, deduplicated, freshly-dated feed ready to hand to a user or an LLM. Use format=rss for feed readers, format=embed or format=ticker for a ready-made widget on your site, and q when you need one subject inside a topic.

Next steps

Response format

Full response structure and result fields.

Content retrieval

Fetch the full text of any article returned in a feed.

News monitoring example

Build a query-driven news monitor with the search endpoint.

Error handling

Status codes and retry strategies.