Web Search API Reference

curl --request POST \
  --url https://api.octen.ai/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "What record did Kendrick Lamar break at the 2026 Grammy Awards?",
  "count": 5
}
'

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "latest WHO guidance on influenza vaccination",
    "results": [
      {
        "title": "Influenza (Seasonal) - World Health Organization (WHO)",
        "url": "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)",
        "highlight": "WHO recommends annual vaccination for high-risk groups\n\n...\n\nSeasonal influenza vaccination policies vary by region...",
        "authors": "World Health Organization",
        "time_published": "2024-10-15T00:00:00Z",
        "time_last_crawled": "2026-01-20T02:12:34Z",
        "favicon": "https://www.who.int/favicon.ico",
        "cover_image": {
          "url": "https://www.who.int/images/default-source/influenza/seasonal-influenza-cover.jpg",
          "description": "Seasonal influenza vaccination"
        },
        "images": [
          {
            "url": "https://www.who.int/images/default-source/influenza/influenza-vaccine-vial.jpg",
            "description": "A vial of seasonal influenza vaccine."
          }
        ]
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "full_content_extra_count": 0
    },
    "latency": 237,
    "warning": null
  }
}

{
  "code": 400,
  "msg": "Missing parameter query",
  "request_id": "req_abc123def456"
}

{
  "code": 401,
  "msg": "Invalid API Key",
  "request_id": "req_abc123def456"
}

{
  "code": 403,
  "msg": "Insufficient balance in account",
  "request_id": "req_abc123def456"
}

{
  "code": 429,
  "msg": "Exceeding the rate limit",
  "request_id": "req_abc123def456"
}

{
  "code": 500,
  "msg": "Internal error",
  "request_id": "req_abc123def456"
}

POST

curl --request POST \
  --url https://api.octen.ai/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "What record did Kendrick Lamar break at the 2026 Grammy Awards?",
  "count": 5
}
'

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "latest WHO guidance on influenza vaccination",
    "results": [
      {
        "title": "Influenza (Seasonal) - World Health Organization (WHO)",
        "url": "https://www.who.int/news-room/fact-sheets/detail/influenza-(seasonal)",
        "highlight": "WHO recommends annual vaccination for high-risk groups\n\n...\n\nSeasonal influenza vaccination policies vary by region...",
        "authors": "World Health Organization",
        "time_published": "2024-10-15T00:00:00Z",
        "time_last_crawled": "2026-01-20T02:12:34Z",
        "favicon": "https://www.who.int/favicon.ico",
        "cover_image": {
          "url": "https://www.who.int/images/default-source/influenza/seasonal-influenza-cover.jpg",
          "description": "Seasonal influenza vaccination"
        },
        "images": [
          {
            "url": "https://www.who.int/images/default-source/influenza/influenza-vaccine-vial.jpg",
            "description": "A vial of seasonal influenza vaccine."
          }
        ]
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "full_content_extra_count": 0
    },
    "latency": 237,
    "warning": null
  }
}

{
  "code": 400,
  "msg": "Missing parameter query",
  "request_id": "req_abc123def456"
}

{
  "code": 401,
  "msg": "Invalid API Key",
  "request_id": "req_abc123def456"
}

{
  "code": 403,
  "msg": "Insufficient balance in account",
  "request_id": "req_abc123def456"
}

{
  "code": 429,
  "msg": "Exceeding the rate limit",
  "request_id": "req_abc123def456"
}

{
  "code": 500,
  "msg": "Internal error",
  "request_id": "req_abc123def456"
}

Authorizations

Authorization

string

header

required

Bearer token used for request authentication. Alternatively, you can send the API key in the x-api-key header.

Body

application/json

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.

Maximum string length: 500

count

integer

default:5

Number of results to return.

Required range: 1 <= x <= 100

include_domains

string[]

A list of domains to specifically include in the search results. The site: query operator adds to this list.

Maximum array length: 1200

Maximum string length: 60

Example:

["octen.ai", "wikipedia.org"]

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.

Maximum array length: 1200

Maximum string length: 60

Example:

["spam.com", "ads.example.net"]

include_text

string[]

Strings that must appear in the result page text.

Maximum array length: 5

Maximum string length: 30

exclude_text

string[]

Strings that must not appear in the result page text.

Maximum array length: 5

Maximum string length: 30

time_basis

enum<string>

default:auto

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.

Available options:

auto,

published,

crawled

time_range

enum<string>

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.

Available options:

day,

week,

month,

year,

d,

w,

m,

y

start_time

string<date-time>

Start time for filtering results. ISO 8601 format.

Example:

"2025-01-01T00:00:00+08:00"

end_time

string<date-time>

End time for filtering results. ISO 8601 format.

Example:

"2025-01-01T00:00:00+08:00"

language

enum<string>[]

A list of languages to restrict results to, as ISO 639-1 codes. By default, no language filter is applied.

Available options:

ar,

de,

en,

es,

fr,

hi,

id,

it,

ja,

ko,

nl,

pl,

pt,

ru,

th,

tr,

vi,

zh

Example:

["en", "zh"]

highlight

object

Controls highlight extraction from result pages.

Show child attributes

full_content

object

Controls whether to return the full raw content of each result page.

Show child attributes

format

enum<string>

default:text

Controls the formatting of highlight outputs.

Available options:

markdown,

text

safesearch

enum<string>

default:strict

Controls filtering of explicit/adult content. off disables filtering; strict drops all adult content.

Available options:

off,

strict

include_images

boolean

default:false

Whether to include images in each result.

Response

Successful search response

request_id

string

required

The unique identifier for this request.

code

integer

Business status code. 0 indicates success.

msg

string

A message describing the result.

data

object

The main response payload.

Show child attributes

APIs

Applications

Web Search API Reference

Authorizations

Body

Response