---
title: "News Search"
method: POST
path: "/news-search"
---

# News Search

`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`

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.

## Request body

- NewsSearchRequest
  - `query` string, 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.
  - `count` integer: Number of results to return.
  - `include_domains` string[]: 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_domains` string[]: 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_time` string, date-time: Start time for filtering results. ISO 8601 format.
  - `end_time` string, date-time: End time for filtering results. ISO 8601 format.
  - `language` string[]: A list of languages to restrict results to, as ISO 639-1 codes. Applies to both `results` and `subjects`.
  - `highlight` HighlightOptions: Controls highlight extraction from result pages.
    - `enable` boolean: If true, returns query-relevant highlight in each result.
    - `max_tokens` integer: Max tokens returned per highlight.
  - `full_content` FullContentOptions: Controls whether to return the full raw content of each result page.
    - `enable` boolean: If true, returns full_content for each result.
    - `max_tokens` integer: Maximum tokens of full content included per result.
  - `subjects` NewsSubjectOptions: Controls subject grouping, which clusters related articles into events.
    - `enable` boolean: If true, returns data.subjects.
    - `count` integer: Maximum number of subjects to return.
    - `max_sub_news` integer: Maximum number of sub-events to return per subject.

## Response `200`

Successful news search response

- NewsSearchResponse
  - `code` integer: Business status code. 0 indicates success.
  - `msg` string: A message describing the result.
  - `request_id` string: The unique identifier for this request.
  - `data` NewsSearchData: The main response payload.
    - `query` string: The original query.
    - `results` NewsSearchResult[]: A list of news results.
      - `title` string: The title of the article.
      - `url` string: The URL of the article.
      - `highlight` string: Query-relevant highlight snippets. Returned only if highlight.enable is true.
      - `full_content` string: Full raw page content. Returned only if full_content.enable is true.
      - `authors` string: Website name or author.
      - `time_published` string, date-time: Publish time in ISO 8601.
      - `time_last_crawled` string, date-time: Last crawl time in ISO 8601.
      - `favicon` string: The favicon URL of the source site.
      - `cover_image` NewsImage: An image attached to an article.
        - `url` string: The image URL.
        - `description` string: Text description of the image.
      - `images` NewsImage[]: In-body images of the article, in order of appearance.
        - `url` string: The image URL.
        - `description` string: Text description of the image.
    - `subjects` NewsSubject[]: A list of subjects, each grouping related articles into one event. Returned only when subjects.enable is true and the query produces at least one subject.
      - `name` string: The event name.
      - `summary` string: A summary of the event.
      - `time_start` string, date-time: When the event started, in ISO 8601.
      - `time_latest` string, date-time: Publish time of the most recent article in the event, in ISO 8601.
      - `top_news` NewsSubjectTopNews: The representative article for the subject.
        - `title` string: The title of the article.
        - `url` string: The URL of the article.
        - `summary` string: A summary of the article, in the language of the original.
        - `highlight` string: Query-relevant highlight snippets. Returned only if highlight.enable is true.
        - `full_content` string: Full raw page content. Returned only if full_content.enable is true.
        - `authors` string: Website name or author.
        - `time_published` string, date-time: Publish time in ISO 8601.
        - `time_last_crawled` string, date-time: Last crawl time in ISO 8601.
        - `favicon` string: The favicon URL of the source site.
        - `cover_image` NewsImage: An image attached to an article.
          - `url` string: The image URL.
          - `description` string: Text description of the image.
        - `images` NewsImage[]: In-body images of the article, in order of appearance.
          - `url` string: The image URL.
          - `description` string: Text description of the image.
      - `sub_news` NewsSubjectSubNews[]: Sub-events within the subject, sorted by event time in descending order.
        - `title` string: The title of the article.
        - `url` string: The URL of the article.
        - `highlight` string: Query-relevant highlight snippets. Returned only if highlight.enable is true.
        - `full_content` string: Full raw page content. Returned only if full_content.enable is true.
        - `authors` string: Website name or author.
        - `time_published` string, date-time: Publish time in ISO 8601.
        - `time_last_crawled` string, date-time: Last crawl time in ISO 8601.
        - `favicon` string: The favicon URL of the source site.
        - `cover_image` NewsImage: An image attached to an article.
          - `url` string: The image URL.
          - `description` string: Text description of the image.
        - `images` NewsImage[]: In-body images of the article, in order of appearance.
          - `url` string: The image URL.
          - `description` string: Text description of the image.
  - `meta` NewsSearchMeta: Additional metadata for the search request.
    - `usage` NewsSearchUsage: Usage information for the search request.
      - `num_search_queries` integer: Number of text search queries executed.
      - `num_subject_search_queries` integer: Number of subject search queries executed. 0 when subjects.enable is false.
      - `full_content_extra_count` integer: Billable full_content results beyond the free allowance.
    - `latency` number: Response time in milliseconds.
    - `warning` string, nullable: Warning message, if any.

## Other responses

- `400`: Invalid or missing parameter.
- `401`: Invalid API Key — Returned when the API key is missing or invalid.
- `403`: Insufficient balance in account — Returned when the account balance is insufficient to complete the request.
- `429`: Exceeding the rate limit — Returned when the request exceeds the configured rate limit.
- `500`: Internal error — Returned when an unexpected server-side error occurs.

---

[API](https://skmtc.dev/octen/apis/octen-api.md) - [All operations](https://skmtc.dev/octen/apis/octen-api/llms.txt) - [OpenAPI document](https://skmtc.dev/octen/apis/octen-api/revisions/aaa6caaf46b0?raw)