octen-search
USE FOR web search, news, company or person lookup, and fast URL lookup. Real-time web search for AI agents powered by Octen, with dedicated endpoints for news (returns storylines, not just articles), business lookup (returns company and person cards), and pulse (predicts the URL a query means in ~10ms, for docs and known sites). Fast, fresh, and relevant — returns ranked results with highlights, full content, domain filtering, and time filtering. Average response under 80ms with minute-level index freshness. Also supports broad (multi-query) search that fans one question into several sub-queries for comprehensive coverage.
How do I install this agent skill?
npx skills add https://github.com/octen-team/octen-skills --skill octen-searchIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The octen-search skill is a legitimate tool providing real-time web, news, and business search capabilities via the Octen API. It follows standard security practices for API authentication and uses encrypted HTTPS for all external communications to the vendor's domain.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 1 issue
What does this agent skill do?
Octen Search
Octen's search skill. It provides real-time web search plus broad (multi-query) search (see Broad Search below). Image and video search live in the separate octen-image-search and octen-video-search skills.
Requires API Key: Get one at https://octen.ai
Set it:
export OCTEN_API_KEY=your-api-key
API Key Setup
Before searching, ensure OCTEN_API_KEY is set. If it is missing — or any call returns 401 — stop and do not retry blindly: tell the user a key is required, point them to https://octen.ai to get one, help them configure it for their agent (below), then continue once it's set.
Configure the key for the relevant agent/runtime:
- Claude Code — add
{ "env": { "OCTEN_API_KEY": "your-key" } }to~/.claude/settings.json(a transient shellexportwill not persist) - Cursor / Hermes / generic shell —
export OCTEN_API_KEY="your-key"in~/.zshrcor~/.bashrc - Codex —
~/.codex/config.toml→[shell_environment_policy],set = { OCTEN_API_KEY = "your-key" } - OpenClaw — add
OCTEN_API_KEY=your-keyto~/.openclaw/.env
See the README for full per-agent instructions.
Quick Start (cURL)
Basic Search
curl -s -X POST "https://api.octen.ai/search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{"query": "latest AI research 2026", "count": 5}'
With Highlight and Time Filtering
curl -s -X POST "https://api.octen.ai/search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "summary judgment",
"count": 10,
"time_basis": "published",
"start_time": "2025-01-01T00:00:00Z",
"end_time": "2026-01-01T00:00:00Z",
"highlight": {"enable": true, "max_tokens": 300}
}'
With Domain Filtering
curl -s -X POST "https://api.octen.ai/search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "climate change policy",
"count": 5,
"include_domains": ["nature.com", "science.org"],
"exclude_domains": ["spam.com"]
}'
With Language Filtering
curl -s -X POST "https://api.octen.ai/search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "climate change 2026",
"count": 5,
"language": ["ja", "zh"]
}'
With Full Content
curl -s -X POST "https://api.octen.ai/search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "latest WHO guidance on influenza vaccination",
"count": 5,
"full_content": {"enable": true, "max_tokens": 1000}
}'
Endpoint
POST https://api.octen.ai/search
Authentication: X-Api-Key: <API_KEY> header
Content-Type: application/json
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | - | Search query (max 500 chars) |
count | integer | No | 5 | Number of results (1–100) |
include_domains | string[] | No | - | Only include results from these domains (max 1200 domains, each max 60 chars) |
exclude_domains | string[] | No | - | Exclude results from these domains (max 1200 domains, each max 60 chars) |
include_text | string[] | No | - | Strings that must appear in result page text (max 5 items, each max 30 chars) |
exclude_text | string[] | No | - | Strings that must not appear in result page text (max 5 items, each max 30 chars) |
language | string[] | No | [] | Filter results to these languages, as ISO 639-1 codes (e.g. ["en", "ja"]). Supported: ar, de, en, es, fr, hi, id, it, ja, ko, nl, pl, pt, ru, th, tr, vi, zh. Empty = no language filter. See https://localizely.com/iso-639-1-list/ |
time_basis | string | No | auto | Time field used for filtering: auto, published, crawled |
start_time | string | No | - | Start time filter, ISO 8601 (e.g. 2025-01-01T00:00:00Z) |
end_time | string | No | - | End time filter, ISO 8601 (must be after start_time) |
highlight | object | No | {"enable": true} | Highlight options (see below) |
format | string | No | text | Output format for highlights: text or markdown |
safesearch | string | No | strict | Adult content filter: off or strict |
full_content | object | No | {"enable": false} | Full content options (see below) |
include_images | boolean | No | false | Return the page's cover image and in-body images per result (see Response Fields). For searching for images, use the octen-image-search skill instead |
Highlight Options
| Field | Type | Default | Description |
|---|---|---|---|
enable | boolean | true | Return query-relevant highlights in each result |
max_tokens | integer | 512 | Max tokens per highlight (100–20000) |
Full Content Options
| Field | Type | Default | Description |
|---|---|---|---|
enable | boolean | false | Return full raw page content for each result |
max_tokens | integer | 2048 | Max tokens per result (100–100000) |
Response Format
Response Fields
| Field | Type | Description |
|---|---|---|
code | integer | Status code. 0 = success |
msg | string | Human-readable status message |
request_id | string | Unique request identifier |
data.query | string | The original query |
data.results[] | array | List of search results |
data.results[].title | string | Page title |
data.results[].url | string | Page URL |
data.results[].highlight | string? | Query-relevant snippets (when highlight.enable is true) |
data.results[].full_content | string? | Full page content (when full_content.enable is true) |
data.results[].authors | string? | Website name or author |
data.results[].time_published | string? | Publish time, ISO 8601 |
data.results[].time_last_crawled | string? | Last crawl time, ISO 8601 |
data.results[].favicon | string? | Favicon URL of the result site |
data.results[].cover_image | object? | Page cover image {url, description} (when include_images is true and the page has one) |
data.results[].images[] | array? | In-body images of the page as {url, description}, in order of appearance (when include_images is true) |
meta.usage.num_search_queries | integer | Number of search queries executed |
meta.usage.full_content_tokens | integer | Total tokens returned in full_content |
meta.latency | number | Response time in milliseconds |
meta.warning | string? | Warning message, if any |
JSON Example
{
"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"
}
]
},
"meta": {
"usage": {
"num_search_queries": 1,
"full_content_tokens": 0
},
"latency": 237,
"warning": null
}
}
Broad Search
Broad Search expands your query into several related sub-queries from different angles, searches them concurrently, and returns results grouped per sub-query (not deduplicated across groups) — ready to ground a complete answer.
Use it when a single /search only reaches a few of the relevant subtopics:
- Comparisons across many sources (pricing, products, vendors)
- Surveys / deeper research
- Multi-angle questions that have more than one facet
For a single focused lookup, use plain /search instead.
Pass the original query as-is — Octen generates the sub-queries for you, so
do not rewrite or pre-split the question into multiple calls; to widen
coverage, raise max_queries (default 5; up to 30 for surveys/research,
lower for a tighter search).
Endpoint
POST https://api.octen.ai/broad-search
Example
curl -s -X POST "https://api.octen.ai/broad-search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "compare cloud GPU pricing across major providers",
"max_queries": 5,
"search_options": {"count": 10, "highlight": {"enable": true}}
}'
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | - | Original search query (max 500 chars) |
max_queries | integer | No | 5 | Upper bound on the number of sub-queries generated (1–30); raise toward 30 for surveys/research, lower for a tighter search |
search_options | object | No | - | Options applied to each sub-query — same fields and defaults as the Parameters table above (count, include_domains, language, time filters, highlight, full_content, include_images, …) |
Response
Same envelope (code, msg, request_id, meta) as Search. data contains:
| Field | Type | Description |
|---|---|---|
data.query | string | The original query |
data.queries[] | string[] | The generated sub-queries |
data.search_results[] | array | One result group per sub-query |
data.search_results[].query | string | The sub-query for this group |
data.search_results[].results[] | array | Results for that sub-query (same shape as Search data.results[]) |
data.search_results[].latency | integer | Latency for that sub-query, in milliseconds |
News Search
News Search is its own endpoint, not /search with a flag. Alongside ranked
articles it returns subjects: the coverage grouped into storylines, each
with a summary and the span it covers — so "what happened with X" is answerable
without reading every article. Read the storylines first; the articles are the
evidence behind them.
include_domains / exclude_domains filter data.results only — never
data.subjects. The storylines are built from the open web regardless, so a
question that restricts its sources ("what is Reuters reporting on X") has to be
answered from data.results. Answering it from the storylines cites outlets the
caller excluded.
Use it for what is being reported right now: breaking events, announcements, coverage of a company or person over the last days or weeks. For a company or person profile — financials, key people, career history — use Business Search below, which returns that as structured cards instead of articles.
Endpoint
POST https://api.octen.ai/news-search
Example
curl -s -X POST "https://api.octen.ai/news-search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "EU AI Act enforcement",
"count": 10,
"time_range": "week",
"subjects": {"count": 3}
}'
Parameters
Same fields and defaults as the Parameters table above except
include_text / exclude_text, format, safesearch and include_images,
which this endpoint does not take — plus:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
subjects | object | No | on | {enable, count (def 2, 1–5), max_sub_news (def 5, 1–20)} — group the coverage into storylines. Omit to take the server default. |
Response
Same envelope (code, msg, request_id, meta) as Search. data.results[]
has the same shape as Search's, plus:
| Field | Type | Description |
|---|---|---|
data.subjects[] | array | One per storyline; present only when subjects.enable and at least one was found. Not subject to include_domains / exclude_domains — see above |
data.subjects[].name | string | The storyline |
data.subjects[].summary | string | What it amounts to |
data.subjects[].time_start / .time_latest | string | The span it covers |
data.subjects[].top_news | object | The lead article, with its own summary |
data.subjects[].sub_news[] | array | Supporting articles |
Business Search
Business Search returns the companies and people behind a query as entity cards — profile, identifiers, financial and stock metrics, key people, career history, recent announcements — alongside the ranked sources. Name two companies in one query and each gets a card with the same fields, ready to compare.
The cards are the point. They carry what a model would otherwise assemble by reading a dozen pages, so a company question costs a fraction of the context.
Use it for questions about a business or the people in one: what a company
does, due diligence, who runs it, how two compare, what they have announced
lately. For breaking coverage of an event use News Search; for general web pages
use plain /search. Set entities.enable to false for a plain ranked list.
Endpoint
POST https://api.octen.ai/business-search
Example
curl -s -X POST "https://api.octen.ai/business-search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{
"query": "compare Stripe and Adyen payment processing",
"count": 10,
"entities": {"count": 2, "max_news": 5}
}'
Parameters
Same fields and defaults as the Parameters table above except
include_text / exclude_text, format, safesearch and include_images,
which this endpoint does not take — plus:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
entities | object | No | on | {enable, count (def 2, 1–20), max_activities (def 5, 1–20), max_news (def 5, 1–20)}. Omit to take the server default. |
The domain, time and language filters narrow the ranked results only — never the entity cards.
Response
Same envelope (code, msg, request_id, meta) as Search. data.results[]
has the same shape as Search's, plus:
| Field | Type | Description |
|---|---|---|
data.entities[] | array | One card per company or person |
data.entities[] (company) | object | name, summary, aliases, identifiers, attributes, metrics, key_people, logo, activities, news |
data.entities[] (person) | object | name, summary, linkedin_url, current_position, career, photo, activities, news |
Pulse Search
Pulse Search predicts the URL a query most likely means instead of searching for it. One inference replaces query understanding, recall and ranking, so it answers in roughly 10ms for a fraction of the cost.
Use it for reaching a page you could almost name: official docs and API references, help centres, a site you know exists.
"github docs"→ the docs site"python list methods"→ the reference page"how do I return an amazon order"→ the help page"youtube"→ the destination
Do not reach for it instead of /search. It sees no fresh content and
takes no filters — no include_domains, no language, no time window. News,
recent events, anything needing freshness: use News Search. A question that
needs real retrieval across the open web: use Search. Pulse is not a cheaper
substitute for either; it answers a different question.
Endpoint
POST https://api.octen.ai/pulse-search
Example
curl -s -X POST "https://api.octen.ai/pulse-search" \
-H "Content-Type: application/json" \
-H "X-Api-Key: ${OCTEN_API_KEY}" \
-d '{"query": "github docs", "count": 5}'
Parameters
A different set from the Parameters table above — none of the domain, text, time or language filters apply here.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | Yes | - | What to find the destination for (max 500 chars) |
mode | string | No | lite | lite or standard — see below |
count | integer | No | 5 | Results (1–10, not 1–100) |
safesearch | string | No | strict | off / strict |
include_images | boolean | No | false | No effect in lite |
highlight | object | No | - | {enable (def true), max_tokens (def 512, 100–20000)}. No effect in lite |
full_content | object | No | - | {enable (def false), max_tokens (def 2048, 100–100000)}. No effect in lite |
lite vs standard
lite (default) | standard | |
|---|---|---|
| Returns | title + URL | adds highlight, full content, images, authors, timestamps, favicon |
| Latency | ~10ms P50 | ~23ms P50 |
| Use when | a URL and a title are enough | the page content itself is needed |
⚠️ In
litethe URL comes back without a scheme —github.com/docs, nothttps://github.com/docs. Prependhttps://before fetching or passing it to Extract.
The first result's full content per search is free; further results are billed.
Response
Same envelope (code, msg, request_id, meta) as Search. data.results[]
has the Search result shape, except that in lite only title and url are
populated. meta.usage adds billed_mode (lite or standard).
Error Codes
| HTTP Status | Description |
|---|---|
400 | Missing or invalid parameter |
401 | Invalid or missing API key |
403 | Insufficient balance |
429 | Rate limited |
500 | Internal server error |
Security
- API key is sent only to the hardcoded endpoint
https://api.octen.ai/searchvia HTTPS - Authentication uses the standard
X-Api-Keyheader - No environment variables are sent to any other endpoints or external services
Notes
- Highlight is enabled by default — set
"highlight": {"enable": false}to disable - Full content is disabled by default — enable it to get raw page text for RAG/grounding
- Use
include_domains/exclude_domainsto scope results to trusted sources - Use
language(ISO 639-1 codes, e.g.["ja", "zh"]) to filter results by language — on Broad Search set it insidesearch_options, not top-level - Use
start_time/end_timewithtime_basisto filter by publish or crawl time format: "markdown"returns highlights in markdown;format: "text"returns plain text
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/octen-team/octen-skills/octen-search">View octen-search on skillZs</a>