> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keenable.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Every page is listed in https://docs.keenable.ai/llms.txt. To pick a product for a job, read https://docs.keenable.ai/choose.md
> Setup steps for agents, covering the SDKs, the MCP server and the CLI: https://docs.keenable.ai/skill.md
> Keenable search and fetch work without an API key. To add them to code, use the official SDK for the project's language: https://docs.keenable.ai/sdks.md
> Without a key, call POST https://api.keenable.ai/v1/search/public or GET https://api.keenable.ai/v1/fetch/public with an X-Keenable-Title header that names your app.
> With a key, send it in the X-API-Key header and read it from the KEENABLE_API_KEY environment variable. Never ask a user to paste a key into chat. Every access method: https://docs.keenable.ai/auth.md
> To get an API key without the console, use device login: https://docs.keenable.ai/authentication.md#device-login
> MCP server: https://api.keenable.ai/mcp (no key, or X-API-Key; keyless Codex uses https://api.keenable.ai/mcp-public), or https://api.keenable.ai/mcp-oauth for OAuth sign-in. These docs are an MCP server at https://docs.keenable.ai/mcp and the OpenAPI spec is at https://docs.keenable.ai/api-reference/openapi.json
> Keenable searches and fetches public web pages. If a question needs no web information, skip the call.
> On 402 with an API key (code insufficient_credits), stop and ask a human to add credits; don't retry. On 429, wait the number of seconds in Retry-After, then retry. Before you ship, follow https://docs.keenable.ai/production.md
> Every error, with its cause and fix, is in https://docs.keenable.ai/errors.md and moving from another search API is covered in https://docs.keenable.ai/migrate.md
> Before you compare Keenable with another search API, read https://docs.keenable.ai/guides/evaluate-search-apis.md

# Production checklist for the Keenable API

> Ship Keenable search and fetch to production: keys from the environment, rate limits, retries on 429 with Retry-After, stopping on 402, timeouts and status.

Take a Keenable integration from a working test to production. Each row below is one change to make before real traffic arrives, with the page that has the details.

| Check | What to do | Details |
| - | - | - |
| API key | Read it from `KEENABLE_API_KEY`. Never hard-code it or ask a user to paste it into chat. | [Read the key from the environment](#read-the-key-from-the-environment) |
| Rate limit | Stay under 10 requests per second per organization, or 25 after \$1,000 of top-ups. | [Stay under your rate limit](#stay-under-your-rate-limit) |
| `429` and `5xx` | Wait the seconds in `Retry-After`, then retry. Retry a `5xx` at most 3 times. | [Retry on 429 and 5xx](#retry-on-429-and-5xx) |
| `402` | Stop. Don't retry. Ask a human to top up. | [Stop on 402](#stop-on-402) |
| Timeouts | Keep a client timeout on every call. The SDKs default to 30 seconds. | [Set timeouts](#set-timeouts) |
| Keyless calls | Send `X-Keenable-Title` with your app's name. | [Name your app on keyless calls](#name-your-app-on-keyless-calls) |
| Agent runs | Send the same `session_id` on every call in one run. | [Group a run with a session ID](#group-a-run-with-a-session-id) |
| Fetch | Leave `live` out unless the page changes between visits. | [Choose indexed or live fetch](#choose-indexed-or-live-fetch) |
| Outages | Check [status.keenable.ai](https://status.keenable.ai) before retrying for long. | [Watch the status page](#watch-the-status-page) |

## Read the key from the environment

The SDKs read your key from `KEENABLE_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:

```bash theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
export KEENABLE_API_KEY=keen_...   # your API key, from the console
```

Over raw HTTP, send the key in the `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](https://docs.keenable.ai/api-keys.md) and [Authentication](https://docs.keenable.ai/authentication.md).

An agent never asks a user to paste a key into chat. To get a key from a tool, use [device login](https://docs.keenable.ai/authentication.md#device-login).

## Stay under your rate limit

| How you call | Limit |
| - | - |
| With an API key | 10 requests per second per organization, shared by all its keys, with no hourly cap |
| Without a key | 1,000 requests per hour and 10 per second per IP address |

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](https://keenable.ai/contact). See [Rate limits](https://docs.keenable.ai/rate-limits.md#raise-your-limit).

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](https://docs.keenable.ai/guides/high-volume-research.md) has a sample with a concurrency cap and retries.

## Retry on 429 and 5xx

A `429` 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`: wait `retry_after_seconds`, then retry.
* `"retryable": false`: change the request or follow `fix`. Sending it again returns the same error.
* No body you can read, such as a proxy error page: retry `408`, `429`, `5xx` and connection failures with growing waits. Don't retry other `4xx`.

The [SDKs](https://docs.keenable.ai/sdks.md) retry for you, up to 2 times by default, and wait `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](https://docs.keenable.ai/errors.md#retry-rules).

## Stop on 402

A `402` 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](https://docs.keenable.ai/auto-top-up.md). 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](https://docs.keenable.ai/errors.md#402) and [Balance and usage](https://docs.keenable.ai/credits.md).

## 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](https://docs.keenable.ai/sdks.md) and [`target_timeout`](https://docs.keenable.ai/errors#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](https://docs.keenable.ai/guides/keyless-access.md).

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: the `X-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](https://docs.keenable.ai/guides/high-volume-research.md#group-a-run-with-a-session-id).

## Choose indexed or live fetch

| Request | What fetch reads | Billed as |
| - | - | - |
| No `live`, Keenable has a usable indexed copy | The indexed copy | `fetch` |
| No `live`, no usable indexed copy | The page from its source | `fetch.live` |
| `live=true` | The page from its source | `fetch.live` |

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](https://docs.keenable.ai/guides/live-fetch.md).

## Watch the status page

[status.keenable.ai](https://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 with `5xx` or time out, before you retry for long. To report a problem, include the `X-Request-Id` header from the response. See [Get help](https://docs.keenable.ai/help.md) and [Report a problem](https://docs.keenable.ai/errors.md#report-a-problem).

## Next steps

* [Errors](https://docs.keenable.ai/errors.md): every error code, its cause and the fix.
* [Best practices](https://docs.keenable.ai/best-practices.md): write queries, filter results and keep them small.
* [Guides](https://docs.keenable.ai/guides.md): task guides for search, fetch and Monitors.
* [Data and privacy](https://docs.keenable.ai/data-privacy.md): what Keenable logs from each request, and zero data retention.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.