SearchEndpoints

POST /v1/search

Scope: search
Tier: Starter and up
Price: $0.0005 to $0.003 per query, see Search pricing
Free credit: Yes, once Starter opens it

Search Kaer's own index, alone or racing the live web, and get ranked results.

Before you begin

A key with the search scope. See Authentication.
An account on the Starter tier or above. Search is locked on the Free tier until your first top-up.
A lane for your query. See Choose a lane.

Request body

Parameter	Type	Default	Description
`query`Required	string	·	1 to 512 characters after trimming.
`lane`	string	`auto`	`web`, `fast`, `deep` or `auto`, case-insensitive. Anything else is a 400.
`num_results`	integer	`5`	Results per query, 1 to 25. Numbers outside are clamped; anything that is not a number is a 400. Also read as `numResults`.
`include_domains`	string[]	·	Only results from these hosts or their subdomains, up to 20. The `web` lane applies it before ranking; the others filter after retrieval. Also `includeDomains`.
`exclude_domains`	string[]	·	Never return results from these hosts or their subdomains, up to 20. Also `excludeDomains`.
`fields`	string[]	·	Result keys to keep, 1 to 20 of `title`, `url`, `snippet`, `source`, `published_date`, `text`, `text_truncated`, `text_source`. Leave it out for all of them. Any other name is a 400 `invalid_fields`.

Any other field is not applied, and the response lists it in kaer.ignored_params, so a filter you expected never fails silently. The body is limited to 16 KB.

Choose a lane

Lane	What it does	Per query	Timeout
`web`	Kaer's index alone. Fastest and cheapest.	$0.0005	6 s
`fast`	The index racing the live web.	$0.001	12 s
`deep`	Every lane, re-ranked. Results carry the page's text, up to 4,000 characters, when it could be read.	$0.003	40 s
`auto`	Kaer picks a lane per query. Billed at the lane that served it.	As served	40 s

A query that runs past its lane's timeout fails with 504 search_timeout and is not charged.

Response

Field	Type	Description
`object`	string	`search.result`
`query`	string	The query, trimmed.
`lane`	string	The lane you asked for.
`served_lane`	string	The lane that ran, and the one billed.
`results[].title`	string	Page title.
`results[].url`	string	Page address.
`results[].snippet`	string	Text from the page that matches the query.
`results[].source`	string[]	Which engines returned the page.
`results[].published_date`	string	Publication time (RFC 3339), when known.
`results[].text`	string	Deep only: the page's main text, up to 4,000 characters.
`results[].text_truncated`	boolean	Deep only: the text was cut.
`results[].text_source`	string	Deep only: `page`, or `snippet` when the site would not serve us the page.
`kaer.request_id`	string	Same as `x-request-id`.
`kaer.cost_usd`	number	What the query cost.
`kaer.ignored_params`	string[]	Fields that were not applied, when there are any.

{
  "object": "search.result",
  "query": "latest ai research",
  "lane": "fast",
  "served_lane": "fast",
  "results": [
    {
      "title": "…",
      "url": "https://…",
      "snippet": "…",
      "source": ["kaer_web"]
    }
  ],
  "kaer": { "request_id": "req_…", "cost_usd": 0.001 }
}

Headers: x-request-id and the x-ratelimit-* headers. Search sends no x-kaer-cost-usd header: the cost is kaer.cost_usd in the body.

Errors

Status	Code	When
400	`invalid_json`	The body is not valid JSON. Images also needs a JSON object.
400	`query_required`	`query` is missing or blank.
400	`query_too_long`	`query` is over 512 characters (search) or 300 (images).
400	`invalid_lane`	`lane` is not `web`, `fast`, `deep` or `auto`.
400	`invalid_num_results`	`num_results` is not a number.
400	`invalid_domains`	`include_domains` or `exclude_domains` is not an array of up to 20 host names.
403	`tier_required`	Your tier does not include this service yet.
413	`body_too_large`	The body is over the endpoint's limit: chat 1 MB, search 16 KB, batch 64 KB, images 8 KB, mail 512 KB.
502	`search_failed`	The search service failed. Nothing was charged.
503	`search_busy`	Search is at capacity. Nothing was charged.
504	`search_timeout`	Search ran out of time. Nothing was charged.
502 or 503	`search_unavailable`	Search is unreachable or paused. Nothing was charged.

Run a search

curl https://api.kaer.ai/v1/search \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest ai research",
    "lane": "fast",
    "num_results": 5
  }'