> ## 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

# Run high-volume web research within rate limits

> How to run many searches and fetches in parallel: cap calls in flight, retry a 429 after Retry-After, group a run with a session ID, and raise your limit.

Run hundreds of searches and fetches for one research task without losing calls to `429`. Cap how many calls are in flight, let the SDK wait out `Retry-After`, and tag every call of the run with one session ID.

## Know your limit

Searches and fetches count against the same limit:

| How you call | Rate limit |
| - | - |
| With an API key | 10 requests per second per organization by default, no hourly cap. All keys in the organization share it. |
| With an API key, after \$1,000 of top-ups in 90 days | 25 requests per second per organization |
| Without a key | 1,000 requests per hour and 10 per second per IP address, for each endpoint |

A keyless research run of more than 1,000 calls an hour hits the hourly cap. Use an [API key](https://docs.keenable.ai/api-keys.md) for volume. [Rate limits](https://docs.keenable.ai/rate-limits.md) lists every tier, including pay per request.

## Parameters

| Parameter | In | Type | Default | Limits | What it does |
| - | - | - | - | - | - |
| `X-Keenable-Session-Id` | Header, `/v1/search` | string | None | At most 128 characters | Your own ID for grouping related requests. You can send it as the `session_id` parameter instead; the header wins if you send both. Values over 128 characters are truncated. |
| `session_id` | Body, `/v1/search` | string | None | At most 128 characters | Your own ID for grouping related requests. |
| `session_id` | Query, `/v1/fetch` | string | None | At most 128 characters | Your own ID for grouping related requests. |

## Run many searches with a cap

This sample runs 8 searches with at most 5 in flight, sends one session ID on every call, and reports any query that still hit a limit after the SDK's retries. It runs with no API key:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
// Needs keenable 0.2.0 or later on npm.
import { randomUUID } from "node:crypto";
import { Keenable, KeenableRateLimitError } from "keenable";

const QUERIES = [
  "official Postgres documentation on logical replication slots",
  "postmortem of an outage caused by a full Postgres replication slot",
  "guide to monitoring Postgres replication lag with pg_stat_replication",
  "release notes for the latest PostgreSQL major version",
  "comparison of Postgres logical replication and physical streaming replication",
  "blog post on upgrading Postgres with logical replication and near-zero downtime",
  "Postgres documentation on the max_slot_wal_keep_size setting",
  "troubleshooting guide for Postgres replication slot WAL growth",
];
const IN_FLIGHT = 5; // at most 5 calls in flight at once

async function main() {
  const sessionId = `research-run-${randomUUID()}`; // a new ID for each run
  const client = new Keenable({
    // One ID for every call in this run. The SDK retries a 429 after Retry-After.
    defaultHeaders: { "X-Keenable-Session-Id": sessionId },
    maxRetries: 3,
  });

  const lines: string[] = new Array(QUERIES.length);
  let next = 0;
  async function worker() {
    while (next < QUERIES.length) {
      const i = next++;
      try {
        const results = await client.search(QUERIES[i], { maxResults: 3, snippetMaxLength: 300 });
        lines[i] = `${results.length} results, top: ${results.results[0]?.url ?? "-"}`;
      } catch (err) {
        if (!(err instanceof KeenableRateLimitError)) throw err;
        // Still limited after the retries, or Retry-After was over 60 s
        lines[i] = `skipped: ${err.code}, retry after ${err.retryAfterSeconds} s`;
      }
    }
  }
  await Promise.all(Array.from({ length: IN_FLIGHT }, worker));

  QUERIES.forEach((query, i) => console.log(`${query.slice(0, 48).padEnd(48)}  ${lines[i]}`));
}

main();
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import asyncio
import uuid

from keenable import AsyncKeenable, KeenableRateLimitError

QUERIES = [
    "official Postgres documentation on logical replication slots",
    "postmortem of an outage caused by a full Postgres replication slot",
    "guide to monitoring Postgres replication lag with pg_stat_replication",
    "release notes for the latest PostgreSQL major version",
    "comparison of Postgres logical replication and physical streaming replication",
    "blog post on upgrading Postgres with logical replication and near-zero downtime",
    "Postgres documentation on the max_slot_wal_keep_size setting",
    "troubleshooting guide for Postgres replication slot WAL growth",
]
IN_FLIGHT = 5  # at most 5 calls in flight at once


async def main():
    limit = asyncio.Semaphore(IN_FLIGHT)
    session_id = f"research-run-{uuid.uuid4()}"  # a new ID for each run
    async with AsyncKeenable(
        # One ID for every call in this run. The SDK retries a 429 after Retry-After.
        default_headers={"X-Keenable-Session-Id": session_id},
        max_retries=3,
    ) as client:

        async def search(query):
            async with limit:
                try:
                    results = await client.search(query, max_results=3, snippet_max_length=300)
                except KeenableRateLimitError as err:
                    # Still limited after the retries, or Retry-After was over 60 s
                    return f"skipped: {err.code}, retry after {err.retry_after_seconds} s"
                return f"{len(results)} results, top: {results[0].url if results else '-'}"

        lines = await asyncio.gather(*(search(q) for q in QUERIES))

    for query, line in zip(QUERIES, lines):
        print(f"{query[:48]:<48}  {line}")


asyncio.run(main())
```

```go Go theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"sync"
	"time"

	"github.com/keenableai/keenable-sdk/go"
)

var queries = []string{
	"official Postgres documentation on logical replication slots",
	"postmortem of an outage caused by a full Postgres replication slot",
	"guide to monitoring Postgres replication lag with pg_stat_replication",
	"release notes for the latest PostgreSQL major version",
	"comparison of Postgres logical replication and physical streaming replication",
	"blog post on upgrading Postgres with logical replication and near-zero downtime",
	"Postgres documentation on the max_slot_wal_keep_size setting",
	"troubleshooting guide for Postgres replication slot WAL growth",
}

const inFlight = 5 // at most 5 calls in flight at once

func main() {
	retries := 3
	sessionID := fmt.Sprintf("research-run-%d", time.Now().UnixNano()) // a new ID for each run
	client, err := keenable.New(&keenable.Options{
		// One ID for every call in this run. The SDK retries a 429 after Retry-After.
		Headers:    map[string]string{"X-Keenable-Session-Id": sessionID},
		MaxRetries: &retries,
	})
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	lines := make([]string, len(queries))
	slots := make(chan struct{}, inFlight)
	var wg sync.WaitGroup
	snippetCap := 300
	for i, query := range queries {
		wg.Add(1)
		go func(i int, query string) {
			defer wg.Done()
			slots <- struct{}{}
			defer func() { <-slots }()

			results, err := client.Search(context.Background(), query,
				&keenable.SearchOptions{MaxResults: 3, SnippetMaxLength: &snippetCap})
			var limited *keenable.RateLimitError
			switch {
			case errors.As(err, &limited):
				// Still limited after the retries, or Retry-After was over 60 s
				lines[i] = fmt.Sprintf("skipped: %s, retry after %s", limited.APICode, limited.RetryAfter)
			case err != nil:
				lines[i] = "error: " + err.Error()
			case len(results.Results) == 0:
				lines[i] = "0 results"
			default:
				lines[i] = fmt.Sprintf("%d results, top: %s", len(results.Results), results.Results[0].URL)
			}
		}(i, query)
	}
	wg.Wait()

	for i, query := range queries {
		if len(query) > 48 {
			query = query[:48]
		}
		fmt.Printf("%-48s  %s\n", query, lines[i])
	}
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use std::collections::HashMap;
use std::time::{SystemTime, UNIX_EPOCH};

use keenable::{Client, Error, Options, SearchOptions};
use tokio::task::JoinSet;

static QUERIES: [&str; 8] = [
    "official Postgres documentation on logical replication slots",
    "postmortem of an outage caused by a full Postgres replication slot",
    "guide to monitoring Postgres replication lag with pg_stat_replication",
    "release notes for the latest PostgreSQL major version",
    "comparison of Postgres logical replication and physical streaming replication",
    "blog post on upgrading Postgres with logical replication and near-zero downtime",
    "Postgres documentation on the max_slot_wal_keep_size setting",
    "troubleshooting guide for Postgres replication slot WAL growth",
];
const IN_FLIGHT: usize = 5; // at most 5 calls in flight at once

#[tokio::main]
async fn main() -> Result<(), Error> {
    // A new ID for each run
    let nanos = SystemTime::now().duration_since(UNIX_EPOCH).expect("clock before 1970").as_nanos();
    let session_id = format!("research-run-{nanos}");
    // One ID for every call in this run. The SDK retries a 429 after Retry-After.
    let client = Client::with_options(Options {
        headers: HashMap::from([("X-Keenable-Session-Id".into(), session_id)]),
        max_retries: Some(3),
        ..Default::default()
    })?;

    let mut lines = vec![String::new(); QUERIES.len()];
    for (batch, chunk) in QUERIES.chunks(IN_FLIGHT).enumerate() {
        let mut set = JoinSet::new();
        for (j, query) in chunk.iter().enumerate() {
            let client = client.clone();
            let opts = SearchOptions { max_results: Some(3), snippet_max_length: Some(300), ..Default::default() };
            set.spawn(async move { (batch * IN_FLIGHT + j, client.search_with(query, &opts).await) });
        }
        while let Some(joined) = set.join_next().await {
            let (i, outcome) = joined.expect("search task panicked");
            lines[i] = match outcome {
                Ok(results) => match results.results.first() {
                    Some(top) => format!("{} results, top: {}", results.results.len(), top.url),
                    None => "0 results".into(),
                },
                // Still limited after the retries, or Retry-After was over 60 s
                Err(Error::RateLimit(e)) => format!("skipped: {:?}, retry after {:?}", e.code, e.retry_after),
                Err(e) => return Err(e),
            };
        }
    }

    for (query, line) in QUERIES.iter().zip(&lines) {
        let short: String = query.chars().take(48).collect();
        println!("{short:<48}  {line}");
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
# 8 searches, at most 5 at once (-P 5), all under one session ID.
# --retry retries a 429 and waits for its Retry-After header (curl 7.66.0 or later).
SESSION_ID="research-run-$(date +%s)" # a new ID for each run
printf '%s\n' \
  "official Postgres documentation on logical replication slots" \
  "postmortem of an outage caused by a full Postgres replication slot" \
  "guide to monitoring Postgres replication lag with pg_stat_replication" \
  "release notes for the latest PostgreSQL major version" \
  "comparison of Postgres logical replication and physical streaming replication" \
  "blog post on upgrading Postgres with logical replication and near-zero downtime" \
  "Postgres documentation on the max_slot_wal_keep_size setting" \
  "troubleshooting guide for Postgres replication slot WAL growth" |
  xargs -P 5 -I {} curl -s --retry 3 -X POST https://api.keenable.ai/v1/search/public \
    -H "Content-Type: application/json" \
    -H "X-Keenable-Title: My App" \
    -H "X-Keenable-Session-Id: $SESSION_ID" \
    -d '{"query": "{}", "max_results": 3, "snippet_max_length": 300}'
```

You see one line per query with its result count and top URL. This run was made on 19 November 2026, and the Python output is shown with 3 of 8 lines:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
official Postgres documentation on logical repli  3 results, top: https://postgresql.org/docs/current/logicaldecoding-explanation.html
postmortem of an outage caused by a full Postgre  3 results, top: https://medium.com/beyond-localhost/6be8c52a3fb1?sk=637721028350a012c7b0cc34dd707f21
guide to monitoring Postgres replication lag wit  3 results, top: https://dba.stackexchange.com/questions/157482/metrics-for-monitoring-master-slave-replication
```

A cap on calls in flight isn't a cap per second. If each call returns in under half a second, 5 calls in flight can pass 10 per second. The SDK then retries the `429` after `Retry-After`, so the run slows down instead of failing.

## Handle a 429

Every SDK retries a `429` for you (TypeScript from `keenable` 0.2.0): 2 times by default, waiting for `Retry-After` when the API sends one, and with backoff from 0.5 s up to 8 s when it doesn't. Set `max_retries` (`maxRetries` in TypeScript, `MaxRetries` in Go) on the client to change that.

| What happens | What the SDK does | What your code does |
| - | - | - |
| `429` with `Retry-After` of 60 s or less | Waits, then retries, up to `max_retries` times | Nothing |
| `429` still returned after the last retry | Raises the rate-limit error | Wait `retry_after_seconds`, then retry, or skip the call |
| `429` with `Retry-After` over 60 s, such as `public_rate_limit_hourly` | Raises the rate-limit error at once | Send an API key, or wait until `limit.resets_at` |
| `429` with `target_rate_limited`, `search_rate_limited` or `fetch_rate_limited` | Waits for `Retry-After: 1`, then retries | Nothing. Your own limit isn't the cause. |

The error is `KeenableRateLimitError` in Python and TypeScript, `*keenable.RateLimitError` in Go and `keenable::Error::RateLimit` in Rust. Its `code` says which limit you hit. Over raw HTTP, read the `Retry-After` header or `retry_after_seconds` in the body. Keyed responses don't carry `X-RateLimit-*` headers, so pace keyed calls with the cap above and the retry wait. Keyless responses carry `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the hourly window only. See [429 Rate limit exceeded](https://docs.keenable.ai/errors.md#429).

## Group a run with a session ID

Send the same session ID on every search and fetch in one research run, so Keenable can group the run's requests. The SDKs have no `session_id` argument. Send the `X-Keenable-Session-Id` header with the client's default headers instead, as the sample does: `default_headers` in Python, `defaultHeaders` in TypeScript (from `keenable` 0.2.0), `Options.Headers` in Go and `Options.headers` in Rust. The CLI takes `--session-id`, and the MCP tools take `session_id`.

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| Start every call at once with `asyncio.gather` or `Promise.all` | Cap calls in flight with a semaphore or a worker pool | Hundreds of calls at once go far past 10 per second, and every extra call comes back as `429`. |
| Retry a `429` at once, in a loop | Wait for `Retry-After`, or let the SDK do it | Retrying sooner returns `429` again and uses up the limit for the other calls in the run. |
| Run several keys in parallel to get more throughput | Raise your organization's limit | All keys in an organization share its per-second limit. |
| A keyless run of thousands of calls | Send an API key | Without a key, the limit is 1,000 requests per hour per IP, shared with everything else on that address. |
| Fetch every search result | Answer from snippets, then fetch only what they miss | Each fetch counts against the same limit as a search. See [Search, then fetch](https://docs.keenable.ai/guides/search-then-fetch.md). |

## More than 25 requests per second

Your organization's limit rises from 10 to 25 requests per second once its completed top-ups reach \$1,000 within 90 days. See [Raise your limit](https://docs.keenable.ai/rate-limits.md#raise-your-limit). For more than 25 per second, [contact Keenable](https://keenable.ai/contact). [Plans and volume pricing](https://docs.keenable.ai/pricing.md#plans-and-volume-pricing) covers dedicated capacity.

## API reference

* [Rate limits](https://docs.keenable.ai/rate-limits.md): every tier and the `429` codes.
* [429 Rate limit exceeded](https://docs.keenable.ai/errors.md#429): the error body, headers and SDK errors.
* [Group an agent run with a session ID](https://docs.keenable.ai/best-practices.md#group-an-agent-run-with-a-session-id): the session ID over raw HTTP.


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