Fields in a search response
This request runs one search with your API key and asks for a single short result:curl -X POST "https://api.keenable.ai/v1/search" \
-H "X-API-Key: $KEENABLE_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "open-weights LLM release", "max_results": 1, "snippet_max_length": 180 }'
{
"query": "open-weights LLM release", // the query you sent, unchanged
"mode": "pro", // mode: the mode that served the call
"results": [
{
"title": "Example Labs releases a 70B open-weights model",
"url": "https://example.com/news/example-70b", // a card URL starts with https://cards.keenable.ai/w/
"description": "", // deprecated, always empty: read snippet
"snippet": "Example Labs published the weights of its 70B model under an open license on Monday...", // snippet
"published_at": "2026-11-16T00:00:00Z", // published_at: when the page was published
"acquired_at": "2026-11-16T09:12:44Z" // acquired_at: when Keenable indexed the page
}
],
"usage": { // usage: only on successful calls made with an API key
"sku": "search.pro", // SKU: what the call was billed as
"amount": 1,
"credits": 1, // credit: one credit is $0.004
"paid": false, // false: the call came from the monthly allowance
"credits_remaining": 99999
}
}
X-Request-Id. A keyless call to /v1/search/public returns the same shape without usage. See the Search response for every field.
Search and fetch
| Term | Meaning | Detail |
|---|---|---|
| Search | POST /v1/search returns ranked web pages for a query, best match first, from 1 to 50 results. | Search |
| Result | One ranked page in results, with title, url and, when Keenable knows them, snippet, published_at and acquired_at. | Search response |
snippet | Text from the page, chosen for the query, in markdown. It can start or end mid-sentence, and snippet_max_length caps it at 180 to 10,000 characters. | Search response |
| Card | A result that Keenable writes itself for queries such as prices, exchange rates or facts about a company. Its URL starts with https://cards.keenable.ai/w/ and works for one day. Send disable_cards: true to get web pages in its place. | Search request |
published_at | When the page was published, as an ISO 8601 timestamp in UTC. The field is left out when the publish date is unknown. | Search response |
acquired_at | When Keenable indexed the page. Use it to judge how fresh the snippet is. | Search response |
published_after, published_before | Filters that keep pages published inside a window. published_after is the filter for recent results, and it leaves out pages with no known publish date. | Date and time filters |
acquired_after, acquired_before | Filters on the time Keenable indexed a page, whatever its publish date. Use acquired_after to find pages that are new to the index. | Search request |
query_time | Searches the index as it stood at that moment, so pages acquired later are left out. It sets no lower bound and isn’t a recency filter. | Point-in-time search |
| Mode | How hard a search works: pro, the default, does deeper retrieval, and realtime returns the fastest response. Each mode is billed as its own SKU. | Search request |
| Search operators | A quoted phrase for exact wording, site: for one or more sites, and - to leave out a word, a phrase or a site, written inside query. | Search operators |
exclude_domains | Hosts that never appear in the results, with their subdomains. A leading dot, such as .gov, excludes a whole public suffix. | Exclude domains |
| Fetch | GET /v1/fetch returns one page as markdown in content, with navigation and boilerplate stripped. | Fetch |
| Live fetch | A fetch made from the source page instead of Keenable’s indexed copy, billed as fetch.live. Send live=true to ask for one. Keenable also fetches live when it has no indexed copy. | Fetch gotchas |
Fetch prompt | An instruction of at most 2,000 characters. A model reads the page, and content holds only its answer. | Fetch request |
max_chars | The cap on the characters of fetched content, 50,000 by default. Cut content sets truncated to true, and total_chars gives the full length. | Fetch request |
session_id | Your own ID, up to 128 characters, that groups the requests of one agent session. Send the same value on every call, or send the X-Keenable-Session-Id header. | Search request |
Access and billing
| Term | Meaning | Detail |
|---|---|---|
| Keyless tier | Calls with no API key, on the /public paths or the MCP server. They are free, rate limited per IP address for each endpoint, and return no usage. | Rate limits |
X-Keenable-Title | The header that names your application on a keyless /public call. Without it, the API returns 400 with Missing app identifier. | API authentication |
| API key | A key that starts with keen_, sent in the X-API-Key header or as Authorization: Bearer. It belongs to your organization and never expires on its own. | API keys |
| Organization | The account that owns your API keys. All its keys share one per-second rate limit. | Rate limits |
| Device login | A sign-in for tools that can’t show a sign-in page, following RFC 8628. Your tool requests a code, a person approves it in the console, and your tool collects a new API key. keenable login uses it. | Device login |
| Monthly allowance | The free requests each month that an organization gets with an API key. Keenable uses it before your prepaid balance. | Monthly allowance |
usage | The object on each successful keyed response that says what the call was billed: sku, amount, credits, paid and credits_remaining. | Reading usage per call |
| Credit | The unit usage.credits reports. One credit is $0.004, so a call at $4 per 1,000 costs 1 credit. | Pricing |
| SKU | The name a call is billed under: search.pro, search.realtime, fetch or fetch.live. | What each call costs |
| Auto top-up | A setting that charges your saved card when your prepaid balance falls below a threshold you set. It is off until you turn it on. | Auto top-up |
X-Request-Id | The response header that identifies one request. Include it when you report a problem, so support can find the request in the logs. | What to include |
Retry-After | The header on a 429 that says how many seconds to wait before you retry. | When you hit a limit |
| x402 | An open payment protocol built on HTTP 402 Payment Required. An agent with a wallet pays for each search or fetch in USDC on Base on the /v1/x402/* paths, with no account. | Pay per request |
| ZeroClick | A storefront where an agent with no account buys a prepaid balance and spends it on searches and fetches. | Prepaid credits through ZeroClick |
| Zero data retention (ZDR) | A data retention policy that Keenable sets for an organization. It follows the API key, and a fetch with a prompt returns 400 with zdr_prompt_unsupported under it. | Zero data retention |
MCP, agents and crawlers
| Term | Meaning | Detail |
|---|---|---|
| MCP | The Model Context Protocol, the way agent clients such as Claude Code and Cursor discover and call tools. The Keenable MCP server at https://api.keenable.ai/mcp gives an agent the search_web_pages and fetch_page_content tools. | MCP server |
| Streamable HTTP | The MCP transport that the remote Keenable server speaks. In a config file it is usually "type": "http", and in Cline it is "type": "streamableHttp". | Other MCP clients |
| MCP URLs | /mcp takes no key or an API key, /mcp-oauth is for clients that sign in through a browser, and /mcp-public publishes no OAuth discovery metadata. All three serve the same web tools. | Which URL to use |
| Local bridge | The @keenable/mcp package, which runs as a local stdio server and forwards calls with your API key. Clients that accept only local servers, such as Claude Desktop, need it. | Local bridge |
| Agent skill | The keenable-web-search skill: instructions and one Python script that let an agent search without an MCP client or an API key. | Agent skill |
| SELECT | A separate MCP server that needs a Keenable account. Your agent writes one read-only SQL SELECT, and the server returns a table built from live web pages. | SELECT |
| Result set | The stored output of a SELECT query, with an id that a later query can put in FROM to read the rows again without new searches. | Result sets |
| KeenableBot | The crawler that collects public pages for the Keenable index. It follows robots.txt. | Keenable crawlers |
| Keenable-User | The user agent of a request made for a person or agent who asked for one page, such as a live fetch. It doesn’t crawl. | Keenable crawlers |
Monitors
| Term | Meaning | Detail |
|---|---|---|
| Monitor | A standing query on a topic. Keenable checks every page it crawls against your monitors and keeps the pages that report something new. It needs an API key. | Monitors |
| Monitor result | A page a monitor kept, with the fields of a search result plus summary, importance and matched_at. | Read the results |
importance | How much a result matters for the monitor’s topic, from 1 to 5. A monitor doesn’t accept pages under 3. | Read the results |
| Schedule | When a monitor runs: a cron expression, an interval such as 6h, or once. A monitor runs at most once an hour. | Schedules |
| Run | One scheduled or triggered pass that returns the results found since the previous run, most important first. | What a run returns |
| Webhook event | A JSON body with id, type, created_at, data and metadata that Keenable posts to your webhook. monitor.result.found carries one new page minutes after it was crawled. | Webhook events |
| Delivery | One webhook event sent to your endpoint, with its attempts and last error. A failed delivery is retried with backoff. | List deliveries |
| Webhook signature | An HMAC-SHA256 signature in the webhook-signature header, made with the monitor’s webhook.secret under the Standard Webhooks scheme. Check it on the raw body before you parse it. | Verify a webhook |