Skip to content

Web search and fetch

Which one do you need?

Use this API when your own code or agent decides what to look up and wants the raw results. When a model on Keln should search while it answers, in one request, turn on web search instead.

POST /v1/web/search returns ranked pages for a query. POST /v1/web/fetch reads pages as clean text. Neither involves a model. They take the same API key as every other Keln call, and bill per call.

Price: $10 per 1,000 searches and $10 per 1,000 fetch calls. Keln never bills a call that failed, or a fetch where every URL failed.

curl https://api.keln.ai/v1/web/search \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "gpu spot prices", "max_results": 5 }'
Field Type
query string, required What to search for, up to 1,500 characters
max_results integer 1 to 20. Default 10
allowed_domains list of strings Keep results to these sites, up to 300
blocked_domains list of strings Remove these sites, up to 150
max_age_hours integer 0 to 720. Only pages the search engine read this recently. Use it for data that changes, such as prices and scores. It returns fewer results
{
  "id": "req_6f1c...",
  "object": "web.search",
  "query": "gpu spot prices",
  "results": [
    {
      "url": "https://example.com/gpu-prices",
      "title": "GPU spot prices this week",
      "content": "The passage that matched...",
      "published": "Fri, 06 Nov 2026 10:00:00 GMT"
    }
  ],
  "usage": { "searches": 1, "cost": 0.01 }
}

published is present when the search engine has a date for the page.

Fetch

curl https://api.keln.ai/v1/web/fetch \
  -H "Authorization: Bearer $KELN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "urls": ["https://example.com/pricing"], "query": "enterprise plan price" }'
Field Type
urls list of strings, required 1 to 5 http or https URLs
query string Returns the passages most relevant to it instead of each page's start
max_chars integer The most to return of each page, 500 to 100,000. Default 100,000
{
  "id": "req_9a2e...",
  "object": "web.fetch",
  "results": [
    { "url": "https://example.com/pricing", "title": "example.com", "content": "# Pricing\n..." }
  ],
  "failed": [],
  "usage": { "fetches": 1, "cost": 0.01 }
}

A URL that gave nothing is in failed. That is not an error: the call still answers 200, and a call where every URL failed has "cost": 0.

Errors

Status Code Meaning
400 invalid_request A field is missing, out of range, or unknown. The message names it
400 query_too_long The query is over 1,500 characters
503 web_unavailable Keln can't serve the call right now, and nothing was billed. Try again shortly

Authentication, wallet and rate limit errors are the same as on every other endpoint. See Errors.

Privacy

Keln sends your queries and URLs to a third-party search engine, passes the results back to you, and stores none of them. Its logs keep only their length and count.