Getting started
Account and API key
You need no account and no API key to search or fetch. If you send an API key, your organization gets its own limit of 10 requests per second with no hourly cap, and 100,000 free requests a month. Responses to keyed calls also report what each call cost in ausage object. To add a key, see API keys.
Keyless billing and limits
Keyless requests use no credits. If you don’t send an API key, Keenable allows 1,000 requests per hour and 10 per second per IP address, counted separately for search and for fetch. All traffic from your IP address shares that pool, so other callers on your network reduce your headroom. See Rate limits.The index behind the results
Search and fetch run on Keenable’s own index. Each search result carriesacquired_at, the time Keenable indexed the page, so you can judge how fresh its snippet is. See the Search response.
Search, Fetch and SELECT
Search returns ranked web pages about a topic, each with text from the page insnippet. Fetch returns one page as markdown when you already have its URL. SELECT is 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. Start with Search, Fetch or SELECT.
Search and fetch
Search modes
Search has two modes.pro does deeper retrieval and is the mode a search runs in if you set none and your organization has no other default. realtime returns the fastest response, for latency-sensitive agent loops. Each mode is billed as its own SKU, and the response names the mode that served the call in mode. See the Search request.
Recent results and query_time
To get recent results, set published_after to a date, a timestamp or a relative delta such as 7d. The results then leave out pages with no known publish date. query_time isn’t a recency filter: it searches the index as it stood at that moment and sets no lower bound. See Date and time filters.
Card results
A card is a result that Keenable writes for queries such as prices, exchange rates or facts about a company. Itsurl starts with https://cards.keenable.ai/w/. To get ordinary web pages in place of cards, send disable_cards: true. You still get the same number of results. See the Search request.
Empty description field
The description field is deprecated and always an empty string. Read the page text from snippet on a search result and from content on a fetch response. See Versioning and deprecation.
Pages with no indexed copy, and live=true
By default, Fetch returns Keenable’s indexed copy of a page. If Keenable has no indexed copy, it fetches the page live from the source and bills the call as fetch.live, even if you didn’t send live=true. Send live=true when you need the current version of a page that changes often. See Fetch.
Keys, credits and limits
Cost of a call
Search and fetch each cost one credit, and every organization gets 100,000 free requests a month. Prices are set per organization, so readcredits in the usage object of each keyed response to see what the call cost. Keyless calls and failed calls report no usage. See Pricing and Credits.
Out of credits
If you’ve spent the monthly allowance and have no purchased credits left,/v1/search and /v1/fetch return 402 with the code insufficient_credits. The body’s billing_url links to where you buy credits. Buy a credit package in the console, or wait for the allowance to reset. See Credits.
Purchased credits and auto top-up
Keenable uses your free requests first, so your purchased balance goes down only once the monthly allowance is spent. Auto top-up is off until you turn it on in the console. Once it is on, Keenable charges your saved card the amount you set whenever the purchased balance falls below your threshold, up to your monthly limit. See Auto top-up.429 and 402
Retry a 429, and don’t retry a 402. A 429 means you sent requests faster than your rate limit allows: wait for the time in the Retry-After header, then send the request again. A 402 means your organization is out of credits, and every retry returns the same 402 until someone adds credits or the allowance resets. See Errors.
Connecting
SDK, MCP server, REST API or CLI
All four work without an API key. For a first search with each, see the Quickstart.
Parameters the SDKs don’t send yet
SDK 0.1.x has three gaps. In Python and TypeScript,mode accepts only pro. No SDK sends disable_cards or session_id. fetch takes only a URL, so it sends no live, prompt or max_chars. To use any of these, call the HTTP API. See SDK methods.
A client that keeps using its own web search
If your client has its own web tools, such asWebSearch and WebFetch in Claude Code, turn them off in the client settings. With both sets active, the agent picks between them inconsistently from one call to the next. keenable configure-mcp turns the client’s own web search off for you in Claude Code and OpenCode. See MCP setup in the CLI.
Paying per request without an account
An agent with a wallet can call search and fetch with no account and no API key on the/v1/x402/* paths. Each search or fetch costs $0.01 in USDC on Base, paid over the x402 protocol. If you call Keenable regularly, an API key costs less. See Pay per request.
Help and changes
Report a problem
Email support@keenable.ai about your account, credits or the API. Include theX-Request-Id header value from the response so Keenable can find your request in its logs. For a bug in an SDK or the CLI, open a GitHub issue in its repository. See Get help.
Breaking changes
Within/v1, Keenable ships only backward-compatible changes and announces them in the changelog. A deprecated endpoint, parameter, response field or MCP tool is announced in the changelog and by email to organization owners, and keeps working for at least 90 days after the announcement. Anything the docs mark as experimental can change without that notice. See Versioning and deprecation.