For AI agents: docs.octen.ai/capabilities/news-search.md
News moves fast, and one story arrives as dozens of reports from dozens of outlets within hours. Octen News Search searches live news and returns ranked articles with query-relevant highlights, images, and optional full content. It also groups related coverage into subjects, so a story reads as one event: a summary, a representative article, and the sub-events that make it up. For the full list of parameters, see the [News Search API reference](/api-reference/news-search). ## Why Octen News Search * **Minute-fresh.** Breaking stories become searchable within minutes of publication, so an agent answers from what is being reported right now. * **One story, one event.** Subject grouping clusters related coverage into a single event with its own summary and representative article, so a model gets the whole story in one pass and spends a fraction of the tokens to get it. * **Authoritative sources first.** Ranking favors established outlets and original reporting. * **Follow a story as it develops.** Each subject carries a start time, the time of its latest article, and its sub-events in order. * **Visual by default.** Cover and in-body images come back with every article. For general web pages, use [Web Search](/capabilities/web-search). ## How It Works 1. Send a query. 2. Octen searches its real-time news index and ranks the most relevant articles. 3. The response returns ranked articles, each with a highlight, images, and optional full content. With subject grouping on, it also returns subjects, each with a summary, a representative article, and its sub-events. ## Scenarios ### Latest headlines Send one query and get ranked coverage with highlights ready for a model to read. ```bash theme={null} curl -X POST https://api.octen.ai/news-search \ -H "Content-Type: application/json" \ -H "x-api-key: YOUR_API_KEY" \ -d '{ "query": "Federal Reserve interest rate decision" }' ``` ### Group coverage into events Subject grouping is on by default. Raise `count` to surface more of the distinct events behind a topic, each with its own summary and sub-events. ```json theme={null} { "query": "Federal Reserve interest rate decision", "count": 5, "subjects": { "enable": true, "count": 3, "max_sub_news": 5 } } ``` Read `subjects[].summary` for the event, `top_news` for the article that best represents it, and `sub_news` for how it developed. ### Articles only To work with a plain ranked list, turn subject grouping off. ```json theme={null} { "query": "Federal Reserve interest rate decision", "count": 10, "subjects": { "enable": false } } ``` ### Recent coverage Restrict results to a recent window. Filtering applies to articles and subjects alike. ```json theme={null} { "query": "Federal Reserve interest rate decision", "time_range": "day" } ``` ### Limit or steer your sources Constrain coverage to outlets you trust. ```json theme={null} { "query": "Federal Reserve interest rate decision", "include_domains": ["reuters.com", "apnews.com"] } ``` Domain filters shape the article list. Subject grouping draws on the full index. ### Headlines in one language International stories return coverage in many languages. Restrict them to the ones you need. ```json theme={null} { "query": "日本銀行 金融政策決定会合", "language": ["ja"], "count": 5 } ``` ### Get the original text For the complete article text, turn on full content. Highlights stay on by default. ```json theme={null} { "query": "Federal Reserve interest rate decision", "count": 8, "full_content": { "enable": true, "max_tokens": 4000 } } ``` The full content of the first 10 results per search is free; only additional results are billed. ## Next StepsLast modified on September 20, 2026