The Search API.

#Quickstart

Four steps from nothing to a first result. Every endpoint lives under https://api.kaer.ai/v1.

#1. Create an account

Sign up at api.kaer.ai. New accounts get $10 of free credit, valid for 90 days.

#2. Open search with a top-up

Search is locked on the Free tier and answers 403 tier_required there. Your first top-up of $5 or more moves you to Starter at once: search opens, and the free credit pays for it too.

#3. Make a key with the search scope

In the dashboard, open Keys, create a key and tick search. Copy it right away: it starts with kaer_live_ and is shown only once. Keep it on your server.

#4. Search

curl https://api.kaer.ai/v1/search \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "eu packaging regulation importers",
    "lane": "deep",
    "num_results": 3
  }'

The answer names the lane that ran and what it cost:

{
  "object": "search.result",
  "lane": "deep",
  "served_lane": "deep",
  "results": [
    {
      "title": "The PPWR: EU Regulation for a More Circular Economy and Less Packaging Waste",
      "url": "https://everwave.de/en/2026/07/13/the-ppwr-eu-regulati…",
      "snippet": "The PPWR—Packaging and Packaging Waste Regulation; EU Regulation 2025/40—will take effect on August 12,…",
      "source": ["kaer_web"],
      "text": "The PPWR (Packaging and Packaging Waste Regulation, EU Regulation 2025/40) will take effect on 12 August 2026 and introd…",
      "text_source": "page",
      "text_truncated": false
    },
    { "title": "Regulation (EU) 2025/40 on packaging and packa…", … },
    { "title": "EU Packaging Regulation Training – Become PPWR…", … }
  ],
  "kaer": { "request_id": "req_…", "cost_usd": 0.003 }
}

#Authentication

Every call except GET /v1/models needs a key. Send it as a bearer token:

Authorization: Bearer kaer_live_...

or in an x-api-key header. When Authorization holds a bearer token, it wins.

#Scopes

#What is checked, in order

1. The key exists and is not revoked or expired: else 401 invalid_api_key (no key at all: missing_api_key).
2. The account is active: else 403 account_inactive.
3. The caller's IP is on the key's allow-list, when it has one: else 403 ip_not_allowed.
4. The key has the endpoint's scope: else 403 insufficient_scope.
5. Your tier includes the service: else 403 tier_required.
6. Rate limits: else 429 rate_limit_exceeded.
7. A hold for the call's maximum cost: else 402 (insufficient_credits, monthly_limit_reached or key_budget_exceeded).

Allow-lists, budgets, expiry and rotation are in Key security.

#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

Kaer's own search index, alone or racing the live web, with ranked results.

#Request body

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.

#Lanes

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

#Response

{
  "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 }
}

Rows can carry more fields, such as scores on the deep lane; rely on the ones above.

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

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
  }'

#Batch search

Scope

search

Tier

Starter and up

Price

Per served row, at search prices

Free credit

Yes, once Starter opens it

Many queries in one round trip. Every row shares the lane, the result count and the domain filters.

#Request body

Unread fields come back in kaer.ignored_params. The body is limited to 64 KB, and the whole batch to 40 seconds.

#Billing

• Each row that comes back with ok: true is billed like a single search, at the lane that served it.
• Identical queries run once, but every row is billed, duplicates included.
• Rows that fail carry charged: false and cost nothing.
• While the batch runs, the gateway holds the dearest possible price for every row (auto holds the deep price).
• If the whole batch fails, nothing is charged.

#Response

Rows can carry more diagnostic fields; read only the ones above.

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

#Errors

curl https://api.kaer.ai/v1/search/batch \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["solar panel efficiency 2026", "heat pump grants uk"],
    "lane": "web",
    "num_results": 3
  }'

#Images

Scope

search

Tier

Starter and up

Price

$0.002 per call

Free credit

Yes, once Starter opens it

Real photos, diagrams and illustrations for a subject, from Kaer's picture index with live Wikimedia Commons and Pexels results when the index is thin. Every picture is checked and comes with its licence, a ready-made credit line and whether a business website may reuse it.

#Request body

Other fields come back in kaer.ignored_params. The body is limited to 8 KB; a call times out after 15 seconds.

#Price

One call costs $0.002 whatever count is, even when it finds no pictures. A call that fails is not charged.

#Response

{
  "object": "images.result",
  "query": "sourdough bread",
  "subject": "sourdough bread",
  "count": 12,
  "reusable_only": true,
  "results": [
    {
      "id": "commons:sourdough.jpg",
      "kind": "photo",
      "title": "Sourdough loaf",
      "image_url": "https://upload.wikimedia.org/…",
      "thumb_url": "https://upload.wikimedia.org/…/500px-…",
      "page_url": "https://commons.wikimedia.org/wiki/File:…",
      "host": "commons.wikimedia.org",
      "width": 4000,
      "height": 3000,
      "source": "wikimedia_commons",
      "license": { "name": "…", "code": "cc-by-sa", "label": "CC BY-SA 4.0", "url": "https://creativecommons.org/licenses/by-sa/4.0/" },
      "credit": "Ann K",
      "attribution": "…",
      "credit_line": "…",
      "attribution_required": true,
      "share_alike": true,
      "commercial_ok": true
    }
  ],
  "kaer": { "request_id": "req_…", "cost_usd": 0.002 }
}

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

#Errors

curl https://api.kaer.ai/v1/images \
  -H "Authorization: Bearer $KAER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "sourdough bread", "count": 20, "reusable": true}'

#Choosing a lane

Every lane takes the same request and returns the same shape. Pick by how far the answer has to come from.

On deep, each result also carries text (the page's main text, up to 4,000 characters), text_truncated and text_source: page, or snippet when a site would not serve the page.

auto holds the deep price while it runs, then settles at the lane that answered. served_lane names it, so you always know what you paid for.

#Use from assistants

Kaer's MCP server lets Claude, ChatGPT, Cursor and other MCP clients ask Kaer, and Kaer's web search runs on this index. It is billed to your Kaer account, not to an API platform balance.

It takes a Kaer account key (kaer_sk_…, made in the Kaer app), not a kaer_live_ API key:

claude mcp add --transport http kaer https://app.kaer.ai/api/mcp \
  --header "Authorization: Bearer kaer_sk_…"

Every client, step by step: Connect Claude and ChatGPT over MCP.

#Pricing

Search is billed per query, not per result: a query costs the same with 1 result or 25. The price is set by the lane that served it.

#Rules

• A served query is billed whatever num_results is and however many results come back, an empty list included.
• auto holds the deep price ($0.003) while it runs, then settles at the lane that served it; served_lane names it. If the lane cannot be read, the query is billed as deep.
• In a batch, every served row is billed like a single search, duplicates included. Failed rows are free. The hold is the dearest lane price times the number of rows.
• Queries that fail or time out are not charged.
• Free credit pays for search and images on Starter and up. Search is not open on the Free tier.

#Worked examples

#Errors

Errors are OpenAI-shaped, so any OpenAI client shows them sensibly:

{
  "error": {
    "message": "The model 'gpt-9' does not exist on api.kaer.ai.",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_not_found"
  }
}

type is the OpenAI class; code is the precise reason, so branch on code. A call that fails with an error status is not charged; a stream that breaks after it started is charged for what it sent. The maps service's own errors keep their shape, see Maps.

#Keys and access

#Balance and spend

#Rate limits

#Request

#Service

#Rate limits and tiers

Your tier is earned by money paid in (net of refunds) and time since your first payment, never by spend.

#How tiers rise

#How limits apply

• Requests are counted in fixed 60-second windows, per key and per account; whichever runs out first answers 429 rate_limit_exceeded with Retry-After.
• An edge gateway also caps each key at 12,000 requests a minute (bursts up to 2000), so the per-key limit is the lower of that and your tier's figure.
• Open streams are counted per account; over the limit, 429 too_many_streams.
• The monthly cap counts settled spend plus open holds in the calendar month (UTC). Your own budget in Settings can only lower it.
• The dashboard playground has its own limit of 20 calls a minute.
• Restricted accounts run at Free tier limits.

On the Free tier only models are open and spend is capped at $10 a month, even with $10 of free credit. A first top-up of $5 moves you to Starter at once.

Mail caps are in Mail; top-up limits in Billing.