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. This page shows you how to send it, which scopes it needs and the order in which a request is checked.

#Before you begin

• A key from the dashboard. If you do not have one, follow the Quickstart.
• A list of the endpoints you plan to call, so you can give the key only the scopes they need.

#Send your key

Send the key as a bearer token:

Authorization: Bearer kaer_live_...

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

#Choose scopes

Each scope covers the endpoints listed, and works once your tier reaches the one in Opens at.

#Find out why a request was refused

The gateway runs these checks in order and stops at the first one that fails. The error code tells you which check it was.

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).

To limit a key further with allow-lists, budgets, expiry and rotation, see 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

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

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

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

Not sure which lane to use? Send auto: Kaer picks one per query, and you pay for the lane that served it.

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

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

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

#Batch search

Scope

search

Tier

Starter and up

Price

Per served row, at search prices

Free credit

Yes, once Starter opens it

Send 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 35 seconds.

#Understand how a batch is billed

• Each row that comes back with ok: true is billed like a single search, at the lane that served it.
• Queries that match after trimming, lowercasing and collapsing spaces run once and are billed once; the repeats come back with charged: false and duplicate_of.
• 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 carry only the fields above. Retry timeout, backpressure and upstream_unavailable rows; fix invalid_query rows; internal is ours to fix.

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

Find 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.

#Know what is billed

• 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.

#Estimate your cost

#Errors

When a call fails, the response tells you why. To handle an error:

1. Read error.code in the body. It is the precise reason.
2. Find the code in the tables below, grouped by cause.
3. Apply the fix in the What to do column.

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.

When you write to support, quote the x-request-id header. It names the exact call.

#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.

#Move up a tier

#Understand 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.