News Search

Searches live news and returns ranked articles with model-ready highlights, images, and optional full content. Related articles are also grouped into subjects, each with a summary, a representative article, and its own timeline.

post/news-search

Request

  • Base URL: https://api.octen.ai
  • URL: https://api.octen.ai/news-search
  • Auth: one of:
    • HTTP bearer
    • API key in header x-api-key

Request body

querystring required

The search query.

Operators

  • site:<domain>: restrict results to a single domain. For multiple domains, use include_domains and exclude_domains.
  • -site:<domain>: exclude a single domain from the results.
countinteger

Number of results to return.

include_domainsstring[]

A list of domains to specifically include in the search results. The site: query operator adds to this list. Applies to results only; subject grouping does not support domain filtering.

exclude_domainsstring[]

A list of domains to specifically exclude from the search results. The -site: query operator adds to this list. If a domain appears in both include_domains and exclude_domains, exclude_domains takes precedence. Applies to results only; subject grouping does not support domain filtering.

time_basis'auto' | 'published' | 'crawled'

Determines which time field is used for time filtering. published uses time_published; crawled uses time_last_crawled. Results missing this field are excluded when filtering by time.

time_range'day' | 'week' | 'month' | 'year' | 'd' | 'w' | 'm' | 'y'

Relative time window counting back from the current time based on time_basis. Mutually exclusive with start_time/end_time: if both are provided, start_time/end_time take precedence.

start_timestring date-time

Start time for filtering results. ISO 8601 format.

end_timestring date-time

End time for filtering results. ISO 8601 format.

languagestring[]

A list of languages to restrict results to, as ISO 639-1 codes. Applies to both results and subjects.

Example request

{
  "include_domains": [
    "reuters.com",
    "apnews.com"
  ],
  "exclude_domains": [
    "spam.com",
    "ads.example.net"
  ],
  "start_time": "2026-08-22T00:00:00Z",
  "end_time": "2026-08-24T00:00:00Z",
  "language": [
    "en",
    "zh"
  ]
}

Response

Successful news search response

codeinteger

Business status code. 0 indicates success.

msgstring

A message describing the result.

request_idstring

The unique identifier for this request.

Changes

No recorded changes to this operation across all 1 revision of this API.