News Search API Reference

curl --request POST \
  --url https://api.octen.ai/news-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Federal Reserve interest rate decision",
  "count": 5
}
'

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "Federal Reserve interest rate decision",
    "results": [
      {
        "title": "Federal Reserve raises interest rates by 25 basis points",
        "url": "https://www.example-news.com/markets/fed-raises-rates",
        "highlight": "The committee voted unanimously to lift the benchmark rate to a range of 3.75% to 4.00%...",
        "authors": "Example News",
        "time_published": "2026-09-15T15:32:37Z",
        "time_last_crawled": "2026-09-15T18:04:11Z",
        "favicon": "https://www.example-news.com/favicon.ico",
        "cover_image": {
          "url": "https://cdn.example-news.com/2026/09/fed-building.png",
          "description": "The Federal Reserve building in Washington."
        },
        "images": [
          {
            "url": "https://cdn.example-news.com/2026/09/trading-floor.png",
            "description": "A trading floor after the announcement."
          }
        ]
      }
    ],
    "subjects": [
      {
        "name": "Federal Reserve raises interest rates in first hike since 2023",
        "summary": "The Federal Reserve voted unanimously to raise its benchmark rate by 25 basis points, the first increase since 2023, citing persistent inflation.",
        "time_start": "2026-09-15T05:53:22Z",
        "time_latest": "2026-09-15T15:32:37Z",
        "top_news": {
          "title": "Fed delivers first rate hike in years with unanimous vote",
          "url": "https://www.example-news.com/markets/fed-first-hike",
          "summary": "Policymakers raised the benchmark rate by a quarter point and signaled that further increases depend on incoming inflation data.",
          "highlight": "Every voting member backed the increase, an unusual show of consensus...",
          "authors": "Example News",
          "time_published": "2026-09-15T15:32:37Z",
          "time_last_crawled": "2026-09-15T18:04:11Z",
          "favicon": "https://www.example-news.com/favicon.ico",
          "cover_image": {
            "url": "https://cdn.example-news.com/2026/09/fed-press-conference.png",
            "description": "The chair speaking at the post-meeting press conference."
          },
          "images": []
        },
        "sub_news": [
          {
            "title": "Mortgage rates climb after the Fed announcement",
            "url": "https://www.example-news.com/markets/mortgage-rates-climb",
            "highlight": "Lenders repriced within hours of the decision...",
            "authors": "Example News",
            "time_published": "2026-09-15T09:11:02Z",
            "time_last_crawled": "2026-09-15T12:40:55Z",
            "favicon": "https://www.example-news.com/favicon.ico",
            "cover_image": {
              "url": "https://cdn.example-news.com/2026/09/mortgage-rates.png",
              "description": "A chart of average mortgage rates."
            },
            "images": []
          }
        ]
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "num_subject_search_queries": 1,
      "full_content_extra_count": 0
    },
    "latency": 245,
    "warning": ""
  }
}

{
  "code": 400,
  "msg": "Invalid params. 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

news-search

curl --request POST \
  --url https://api.octen.ai/news-search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Federal Reserve interest rate decision",
  "count": 5
}
'

{
  "code": 0,
  "msg": "success",
  "request_id": "req_abc123def456",
  "data": {
    "query": "Federal Reserve interest rate decision",
    "results": [
      {
        "title": "Federal Reserve raises interest rates by 25 basis points",
        "url": "https://www.example-news.com/markets/fed-raises-rates",
        "highlight": "The committee voted unanimously to lift the benchmark rate to a range of 3.75% to 4.00%...",
        "authors": "Example News",
        "time_published": "2026-09-15T15:32:37Z",
        "time_last_crawled": "2026-09-15T18:04:11Z",
        "favicon": "https://www.example-news.com/favicon.ico",
        "cover_image": {
          "url": "https://cdn.example-news.com/2026/09/fed-building.png",
          "description": "The Federal Reserve building in Washington."
        },
        "images": [
          {
            "url": "https://cdn.example-news.com/2026/09/trading-floor.png",
            "description": "A trading floor after the announcement."
          }
        ]
      }
    ],
    "subjects": [
      {
        "name": "Federal Reserve raises interest rates in first hike since 2023",
        "summary": "The Federal Reserve voted unanimously to raise its benchmark rate by 25 basis points, the first increase since 2023, citing persistent inflation.",
        "time_start": "2026-09-15T05:53:22Z",
        "time_latest": "2026-09-15T15:32:37Z",
        "top_news": {
          "title": "Fed delivers first rate hike in years with unanimous vote",
          "url": "https://www.example-news.com/markets/fed-first-hike",
          "summary": "Policymakers raised the benchmark rate by a quarter point and signaled that further increases depend on incoming inflation data.",
          "highlight": "Every voting member backed the increase, an unusual show of consensus...",
          "authors": "Example News",
          "time_published": "2026-09-15T15:32:37Z",
          "time_last_crawled": "2026-09-15T18:04:11Z",
          "favicon": "https://www.example-news.com/favicon.ico",
          "cover_image": {
            "url": "https://cdn.example-news.com/2026/09/fed-press-conference.png",
            "description": "The chair speaking at the post-meeting press conference."
          },
          "images": []
        },
        "sub_news": [
          {
            "title": "Mortgage rates climb after the Fed announcement",
            "url": "https://www.example-news.com/markets/mortgage-rates-climb",
            "highlight": "Lenders repriced within hours of the decision...",
            "authors": "Example News",
            "time_published": "2026-09-15T09:11:02Z",
            "time_last_crawled": "2026-09-15T12:40:55Z",
            "favicon": "https://www.example-news.com/favicon.ico",
            "cover_image": {
              "url": "https://cdn.example-news.com/2026/09/mortgage-rates.png",
              "description": "A chart of average mortgage rates."
            },
            "images": []
          }
        ]
      }
    ]
  },
  "meta": {
    "usage": {
      "num_search_queries": 1,
      "num_subject_search_queries": 1,
      "full_content_extra_count": 0
    },
    "latency": 245,
    "warning": ""
  }
}

{
  "code": 400,
  "msg": "Invalid params. 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. Applies to results only; subject grouping does not support domain filtering.

Maximum array length: 1200

Maximum string length: 60

Example:

["reuters.com", "apnews.com"]

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.

Maximum array length: 1200

Maximum string length: 60

Example:

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

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:

"2026-08-22T00:00:00Z"

end_time

string<date-time>

End time for filtering results. ISO 8601 format.

Example:

"2026-08-24T00:00:00Z"

language

enum<string>[]

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

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

subjects

object

Controls subject grouping, which clusters related articles into events.

Show child attributes

Response

Successful news 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

News Search API Reference

Authorizations

Body

Response