Read the key from the environment
The SDKs read your key fromKEENABLE_API_KEY. Unset means keyless, so a missing variable in production drops you to the keyless limits. Set it in your deployment’s secret store:
X-API-Key header to /v1/search and /v1/fetch. All keys in an organization share its balance and its rate limit. See API keys and Authentication.
An agent never asks a user to paste a key into chat. To get a key from a tool, use device login.
Stay under your rate limit
Your organization’s limit rises to 25 requests per second once its completed top-ups reach $1,000 within 90 days. The higher limit lasts 90 days from the top-up that crossed $1,000. For more, contact Keenable. See Rate limits.
Searches and fetches count against the same limit. When you send calls in parallel, keep each batch under your per-second limit. High-volume research has a sample with a concurrency cap and retries.
Retry on 429 and 5xx
A429 carries a Retry-After header with the seconds to wait, and the body repeats it as retry_after_seconds. Wait that long, then send the same request again. The body’s code says which limit you hit, such as rate_limit_per_second.
Decide from the body’s retryable field, not the status alone:
"retryable": true: waitretry_after_seconds, then retry."retryable": false: change the request or followfix. Sending it again returns the same error.- No body you can read, such as a proxy error page: retry
408,429,5xxand connection failures with growing waits. Don’t retry other4xx.
Retry-After when the API sends it. A Retry-After over 60 seconds isn’t waited out: the SDK raises the error at once, so your code decides. After a keyless public_rate_limit_hourly, that wait can be up to an hour. An API key removes the hourly cap.
Branch on type and code, never on the text of error or message. See Retry rules.
Stop on 402
A402 with code insufficient_credits means your organization has used its free monthly allowance and its prepaid balance. Every retry returns the same 402. Stop, and ask a human to top up in the console or turn on auto top-up. The body carries billing_url and auto_top_up_url for that.
The SDKs raise KeenableInsufficientCreditsError (Python, TypeScript), *keenable.InsufficientCreditsError (Go) or keenable::Error::InsufficientCredits (Rust). See 402 Out of funds and Balance and usage.
Set timeouts
Every SDK has a client timeout, 30 seconds by default:timeout in Python and Rust, timeoutMs in TypeScript and Timeout in Go. In Python and TypeScript, a timed-out request raises KeenableTimeoutError. Over raw HTTP, set a timeout in your HTTP client.
A fetch of a slow page can fail with 504 and code target_timeout. That response carries Retry-After: 5. Retry up to 3 times, then try another URL. See SDK configuration and target_timeout.
Name your app on keyless calls
Keyless calls go to/v1/search/public and /v1/fetch/public and must send an X-Keenable-Title header that names your app. Without it, the API returns 400 with Missing app identifier. The SDKs send Keenable SDK unless you set the client source. If you build a product on top of an SDK, set it to your product’s name. See Keyless access.
Keyless calls share the per-IP limit with all other traffic from that IP address, and that traffic uses up part of your limit. In production, send an API key instead.
Group a run with a session ID
Send the same ID, up to 128 characters, on every call in one agent run: theX-Keenable-Session-Id header, or session_id in the search body or the fetch query string. The header wins when you send both. No SDK has a session_id argument, so send the header through the client’s default headers. Over MCP, pass session_id as a tool argument. See Group a run with a session ID.
Choose indexed or live fetch
Leave
live out for documentation, articles and papers. Set live=true for pages that change between visits, such as status pages, price lists and schedules. See Live fetch.
Watch the status page
status.keenable.ai shows whether the Search API and the Content API are up, with 90 days of uptime history. Fetch runs on the Content API. Check it when calls fail with5xx or time out, before you retry for long. To report a problem, include the X-Request-Id header from the response. See Get help and Report a problem.
Next steps
- Errors: every error code, its cause and the fix.
- Best practices: write queries, filter results and keep them small.
- Guides: task guides for search, fetch and Monitors.
- Data and privacy: what Keenable logs from each request, and zero data retention.