---
title: "Web Search"
method: POST
path: "/search"
---

# Web Search

`POST /search`

## Request

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

Searches the live web and returns ranked results with model-ready highlights and optional full content. Optional filters narrow sources, time windows, and languages.

## Request body

- SearchRequest
  - `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.
  - `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.
  - `include_text` string[]: Strings that must appear in the result page text.
  - `exclude_text` string[]: Strings that must not appear in the result page text.
  - `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. By default, no language filter is applied.
  - `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.
  - `format` 'markdown' | 'text': Controls the formatting of highlight outputs.
  - `safesearch` 'off' | 'strict': Controls filtering of explicit/adult content. `off` disables filtering; `strict` drops all adult content.
  - `include_images` boolean: Whether to include images in each result.

## Response `200`

Successful search response

- SearchResponse
  - `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` SearchData: The main response payload.
    - `query` string: The original query.
    - `results` SearchResult[]: A list of search results.
      - `title` string: The title of the result page.
      - `url` string: The URL of the result page.
      - `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 result site.
      - `cover_image` object: The page cover image. Returned only when `include_images` is true and the page has a cover image.
        - `url` string: The cover image URL.
        - `description` string: Text description of the cover image.
      - `images` object[]: In-body images of the page, in order of appearance. Returned only when `include_images` is true.
        - `url` string: The image URL.
        - `description` string: Text description of the image.
  - `meta` SearchMeta: Additional metadata for the search request.
    - `usage` SearchUsage: Usage information for the search request.
      - `num_search_queries` integer: Number of search queries executed.
      - `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`: Missing parameter query — Returned when a required parameter is missing.
- `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)