Article endpoints

These are the endpoints that return articles. They share one filter set, one response shape and one pagination model, so the only real decision is how you want to select the articles: by a query, by a taxonomy value in the path, by geography, or by ID.

Start with /v1/news/everything — every other endpoint on this page is a narrowed version of it.

Which one do I need?

You want	Endpoint	Guide
Search or monitor the whole archive	GET /v1/news/everything	Search articles
A front page or breaking-news feed	GET /v1/news/top-headlines	Top headlines
Everything in one IPTC category	GET /v1/news/category/{taxonomy}/{category_id}	Articles by category
A curated beat, such as automotive or commodities	GET /v1/news/topic/{topic_id}	Articles by topic
Coverage of a business sector	GET /v1/news/industry/{industry_id}	Articles by industry
Everything mentioning a person, company, brand or place	GET /v1/news/entity/{entity_id}	Articles by entity
News near a point on the map, sorted by distance	GET /v1/news/local	Local news
Articles the moment they are discovered, unenriched	GET /v1/news/raw	Raw articles (Lite)
One article, or up to 100, by ID	GET /v1/news/article	Get an article by ID
Every outlet that covered the same event	GET /v1/news/story/{article_id}	Get a story

Search and headlines

/v1/news/everything accepts the complete filter set — title, language, date, source, category, topic, industry, entity, sentiment, media, readability, geo — plus sorting, pagination, faceting, highlighting and export. Both GET and POST work; use POST when a filter value is long, such as a boolean query or a list of source IDs.

/v1/news/top-headlines is the same endpoint with one restriction you cannot turn off: publishers with an Open Page Rank of 5 or above. Reach for it when the answer should look like a front page rather than a search result.

Browse by taxonomy

Four endpoints move a single taxonomy value from a filter into the URL path. The value becomes the base set and your remaining filters narrow it:

• Category — IPTC Media Topics, the section the article belongs to. Values come from List of Categories.
• Topic — curated news beats such as industry.automotive_news or market_news.commodities.base_metals. A topic feed follows a beat wherever the story is filed.
• Industry — the sector the news is about, not the section it was filed under.
• Entity — a person, organization, brand, location or product recognised in the text. Matching is on the resolved entity, so Apple the company never collides with the fruit.

Do not know the ID? The autocomplete endpoints turn a name prefix into one.

Geography and the discovery feed

/v1/news/local takes lat/lng or a place name, ranks results by proximity, and adds distance_km and nearest_location to every article — which the plain geo filter on /v1/news/everything does not do.

/v1/news/raw returns articles at the discovery stage, before HTML parsing and NLP. There is no language detection, no categories, topics, entities or sentiment, and only roughly the last 24 hours are retrievable — it is a staging feed, not an archive. Use it when you want the earliest possible access, or when you run your own parsing.

Lookup by ID

/v1/news/article rehydrates articles you stored earlier: pass one id or up to 100 comma-separated IDs in a single request. /v1/news/story/{article_id} goes the other way — from one article to every other article covering the same event, clustered by title similarity.

What every article endpoint shares

• The same response envelope — articles under results, article links under href, paging through next_page. See API Response Structure.
• The same filters — documented in full on the /v1/news/everything page.
• The same pricing — 1 point per request, plus 2 more when you use the prompt parameter (Basic and above; Free and Starter get 403 ER0706), and 1 extra per requested insights block on /v1/news/local. Check the balance with /v1/balance.
• Silent handling of unknown parameters — a misspelled filter returns 200 ok and simply does not apply, so verify names against the parameter tables.

Next steps

• Copy a working request: Usage examples
• Get articles pushed instead of polled: Real-time delivery
• Count or aggregate instead of listing: Insights