# Web search and fetch
!!! tip "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](../capabilities/web-search.md)
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.
## Search
```bash
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 |
```json
{
"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
```bash
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 |
```json
{
"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](errors.md).
## 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.
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.
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.
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.