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:
qcan be up to 200 characters. A longer value returns400.qworks with every format. You can also send it asquery.- With
format=embedorformat=ticker, the widget and the ticker show a relevance-ranked order. Like the otherqresponses, they carry no topic brief. - A
qresponse carries no topic brief:aiSummaryis absent andansweris empty, because the brief describes the whole topic, not your filtered view. - Use
/api/v1/searchwhen 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.
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:
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
Withformat=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 returns404 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 sendq, 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 anx-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 askey:
keyin the URL works only for feed keys.- A feed key works only with
format=rss,format=embedorformat=ticker, and on the topics index. - With
format=json,format=contextor noformat, a feed key gets403. Noformatmeansjson. - A feed key gets
403on every other endpoint. - A full API key in a URL gets
403. Send a full key in thex-api-keyheader.
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.
Where to use the link
Bothembed 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 about48. - Grafana: in a News panel, paste the
format=rsslink 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 needsdisable_sanitize_html = truein your Grafana settings (self-hosted Grafana only). - Feed reader: use the
format=rsslink. - Sandboxed iframes: if you add a
sandboxattribute, includeallow-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.
Keep the link private
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. Useformat=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.

