Article endpoints

Choose an endpoint based on which articles you need: a search result, a category or topic feed, local news, or articles by ID. Article endpoints use the same response format and pagination. Most also share the same filters.

Start with /v1/news/everything for a general search. Other endpoints offer more specific selections.

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 subject such as automotive news 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
The earliest available articles in a basic format	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

Use /v1/news/everything to search with any of the available filters. You can sort results, browse pages, count articles by field, highlight matches and export data. Send filters in the URL with GET or as JSON with POST. POST is useful for long queries or lists of source IDs.

Use /v1/news/top-headlines for a front page or headline feed. It only returns articles from publishers with an Open Page Rank of 5 or above.

Browse by subject

These endpoints select one category, topic, industry or entity in the URL path. Add filters to narrow the results:

• Category — IPTC Media Topics, the section the article belongs to. Values come from List of Categories.
• Topic — a subject such as automotive news (industry.automotive_news) or base metals (market_news.commodities.base_metals). A topic feed returns articles about your subject across news categories.
• Industry — the business sector an article covers.
• Entity — a person, organization, brand, location or product recognised in the text. The filter finds articles about Apple the company, without matching mentions of the fruit.

To find an ID, search by the beginning of a name with the autocomplete endpoints.

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.

Use /v1/news/raw for the earliest available articles or to process the content yourself. It returns a basic format without detected language, categories, topics, entities or sentiment. Only roughly the last 24 hours are available.

Lookup by ID

Use /v1/news/article to fetch saved articles again. Pass one id or up to 100 IDs separated by commas. Use /v1/news/story/{article_id} to find other articles about the same event.

Shared features and endpoint differences

• The same response format — articles under results, article links under href, paging through next_page. See API Response Structure.
• Shared search filters — documented in full on Filters. Article lookup and Story lookup ignore prompt; Raw articles supports a smaller parameter set. Each API reference page lists its own parameters and restrictions.
• 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.
• Check parameter names. An unknown filter is ignored even when the request returns 200 ok. Use the names in 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