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

# Research loop: parallel searches, then capped page reads

> Research a broad question with search and fetch: run focused searches at once, merge results without duplicate URLs, read the top pages with a size cap.

Answer a broad question from several angles without filling your context. Your code splits the question into focused searches and runs them at once, merges the results so each URL appears once, and reads only the top pages, each cut at 3,000 characters. Run it again with follow-up searches when the pages leave a gap.

## Recipe prompt

Paste this into your coding agent to have it build the recipe in your project:

```text Recipe prompt theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
Read https://docs.keenable.ai/recipes/research-loop.md and add a research function to this project with the official Keenable SDK for the project's language. It takes a list of sub-questions, runs at most 5 searches at once with max_results=5, merges the results keeping each URL once in rank order, and fetches the top 3 pages with max_chars=3000. Read KEENABLE_API_KEY from the environment if it is set. Run it on three sub-questions about a topic in this project and show me the source list.
```

## What you build

| Step | Call | Setting | Why |
| - | - | - | - |
| Split | Your code or your model | 3 focused sub-questions | One narrow search per angle ranks better than one wide query |
| Search | Search, in parallel | `max_results: 5`, `snippet_max_length: 300` | Short snippets are enough to pick pages |
| Merge | Your code | Keep the first occurrence of each URL | The same page often ranks for several angles |
| Read | Fetch, top 3 URLs | `max_chars: 3000` | Caps what each page adds to your context |
| Loop | Your model | New sub-questions for the gaps | Stop when the pages answer the question |

## When it runs

Once per research step. A step costs one search per sub-question and one fetch per page you read: 3 searches and 3 fetches in this sample. Searches and fetches share one rate limit, so the step size decides how fast you can loop.

## Code

This sample runs three searches at once, merges them and reads the top 3 pages. 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 { Keenable } from "keenable";

const questions = [
  "how does HTTP/3 connection migration work",
  "QUIC connection ID rotation and privacy",
  "HTTP/3 connection migration support in browsers",
];

async function main() {
  const client = new Keenable(); // keyless: no API key needed to try it

  // 1. Search every sub-question at once
  const searches = await Promise.all(
    questions.map((q) => client.search(q, { maxResults: 5, snippetMaxLength: 300 })),
  );

  // 2. Merge the results, keeping each URL once, in rank order
  const urls = [...new Set(searches.flatMap((s) => s.results.map((r) => r.url)))];

  // 3. Read the top 3 pages, each capped at 3,000 characters
  const pages = await Promise.all(urls.slice(0, 3).map((url) => client.fetch(url, { maxChars: 3000 })));

  console.log(`${urls.length} unique pages from ${questions.length} searches`);
  pages.forEach((page, i) => {
    console.log(`[${i + 1}] ${page.title} (${page.url}) ${page.content.length} chars`);
  });
}

main();
```

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

from keenable import AsyncKeenable

QUESTIONS = [
    "how does HTTP/3 connection migration work",
    "QUIC connection ID rotation and privacy",
    "HTTP/3 connection migration support in browsers",
]


async def main():
    async with AsyncKeenable() as client:  # keyless: no API key needed to try it
        # 1. Search every sub-question at once
        searches = await asyncio.gather(
            *(client.search(q, max_results=5, snippet_max_length=300) for q in QUESTIONS)
        )

        # 2. Merge the results, keeping each URL once, in rank order
        urls = list(dict.fromkeys(r.url for results in searches for r in results))

        # 3. Read the top 3 pages, each capped at 3,000 characters
        pages = await asyncio.gather(*(client.fetch(url, max_chars=3000) for url in urls[:3]))

    print(f"{len(urls)} unique pages from {len(QUESTIONS)} searches")
    for number, page in enumerate(pages, start=1):
        print(f"[{number}] {page.title} ({page.url}) {len(page.content)} chars")


asyncio.run(main())
```

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

import (
	"context"
	"fmt"
	"log"
	"sync"

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

var questions = []string{
	"how does HTTP/3 connection migration work",
	"QUIC connection ID rotation and privacy",
	"HTTP/3 connection migration support in browsers",
}

func main() {
	ctx := context.Background()
	client, err := keenable.New(nil) // keyless: no API key needed to try it
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// 1. Search every sub-question at once
	searches := make([]*keenable.SearchResponse, len(questions))
	var wg sync.WaitGroup
	for i, q := range questions {
		wg.Add(1)
		go func() {
			defer wg.Done()
			snippetCap := 300
			res, err := client.Search(ctx, q, &keenable.SearchOptions{MaxResults: 5, SnippetMaxLength: &snippetCap})
			if err != nil {
				log.Printf("%q: %v", q, err)
				return
			}
			searches[i] = res
		}()
	}
	wg.Wait()

	// 2. Merge the results, keeping each URL once, in rank order
	var urls []string
	seen := map[string]bool{}
	for _, res := range searches {
		if res == nil {
			continue
		}
		for _, r := range res.Results {
			if !seen[r.URL] {
				seen[r.URL] = true
				urls = append(urls, r.URL)
			}
		}
	}

	// 3. Read the top 3 pages, each capped at 3,000 characters
	fmt.Printf("%d unique pages from %d searches\n", len(urls), len(questions))
	for i, url := range urls[:min(3, len(urls))] {
		page, err := client.FetchWithOptions(ctx, url, &keenable.FetchOptions{MaxChars: 3000})
		if err != nil {
			log.Printf("%s: %v", url, err)
			continue
		}
		fmt.Printf("[%d] %s (%s) %d chars\n", i+1, page.Title, page.URL, len([]rune(page.Content)))
	}
}
```

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

use keenable::{Client, FetchOptions, SearchOptions};

const QUESTIONS: [&str; 3] = [
    "how does HTTP/3 connection migration work",
    "QUIC connection ID rotation and privacy",
    "HTTP/3 connection migration support in browsers",
];

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // keyless: no API key needed to try it

    // 1. Search every sub-question at once
    let handles: Vec<_> = QUESTIONS
        .iter()
        .map(|&q| {
            let client = client.clone();
            tokio::spawn(async move {
                let opts = SearchOptions {
                    max_results: Some(5),
                    snippet_max_length: Some(300),
                    ..Default::default()
                };
                client.search_with(q, &opts).await
            })
        })
        .collect();

    // 2. Merge the results, keeping each URL once, in rank order
    let mut seen = HashSet::new();
    let mut urls = Vec::new();
    for handle in handles {
        let results = handle.await.expect("search task panicked")?;
        for result in &results {
            if seen.insert(result.url.clone()) {
                urls.push(result.url.clone());
            }
        }
    }

    // 3. Read the top 3 pages, each capped at 3,000 characters
    println!(
        "{} unique pages from {} searches",
        urls.len(),
        QUESTIONS.len()
    );
    let opts = FetchOptions {
        max_chars: Some(3000),
        ..Default::default()
    };
    for (i, url) in urls.iter().take(3).enumerate() {
        let page = client.fetch_with(url, &opts).await?;
        println!(
            "[{}] {} ({}) {} chars",
            i + 1,
            page.title,
            page.url,
            page.content.chars().count()
        );
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
# 1. Search every sub-question at once, then 2. keep each URL once
for q in "how does HTTP/3 connection migration work" \
         "QUIC connection ID rotation and privacy" \
         "HTTP/3 connection migration support in browsers"; do
  curl -s -X POST https://api.keenable.ai/v1/search/public \
    -H "Content-Type: application/json" \
    -H "X-Keenable-Title: My App" \
    -d "$(jq -n --arg q "$q" '{query: $q, max_results: 5, snippet_max_length: 300}')" &
done | jq -r '.results[].url' | awk '!seen[$0]++' > urls.txt

# 3. Read the top 3 pages, each capped at 3,000 characters
head -n 3 urls.txt | while read -r url; do
  curl -s -G https://api.keenable.ai/v1/fetch/public \
    -H "X-Keenable-Title: My App" \
    --data-urlencode "url=$url" \
    --data-urlencode "max_chars=3000" | jq -r '"\(.title) (\(.url)) \(.content | length) chars"'
done
```

The TypeScript sample needs `keenable` 0.2.0 or later on npm, for the `maxChars` option on `fetch`.

Python uses `AsyncKeenable` with `asyncio.gather`, TypeScript `Promise.all`, Go goroutines and Rust `tokio::spawn` on a cloned client, which shares one connection pool. The curl tab runs the searches in the background and merges their URLs with `awk`, so its merged order follows whichever search answers first.

## Example output

You see how many unique pages the searches found, then one line per page read, with its length after the cap:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
15 unique pages from 3 searches
[1] RFC 9114: HTTP/3 (https://www.rfc-editor.org/rfc/rfc9114.html) 3000 chars
[2] What is HTTP/3? (https://www.cloudflare.com/learning/performance/what-is-http3/) 3000 chars
[3] HTTP/3 (https://http.dev/3) 3000 chars
```

To hand the pages to your model with numbered citations, render each one with the page's `to_context()`, or use search results' `to_context()` when snippets are enough. See [Context size](https://docs.keenable.ai/sdks.md#context-size).

## Production notes

| Situation | What happens | What to do |
| - | - | - |
| Parallel calls | Searches and fetches count against the same limit: 10 per second per organization with an API key, or 10 per second and 1,000 per hour per IP address without one. | Run at most 5 calls at once. See [Parallel calls](https://docs.keenable.ai/rate-limits.md#parallel-calls). |
| `429` | You went over a rate limit. The response carries `Retry-After`. | Wait that many seconds, then retry the call. A keyless hourly `429` repeats until `resets_at`: add an [API key](https://docs.keenable.ai/api-keys.md). |
| `402` with an API key | `insufficient_credits`: your organization used its allowance and prepaid balance. | Stop the loop. Retrying returns `402` again. See [402 Out of funds](https://docs.keenable.ai/errors.md#402). |
| A page can't be fetched | The fetch returns an error such as `target_unreachable`. | Skip it and read the next URL in the merged list. |
| One search fails | The Go sample logs it and merges the others. The Python, TypeScript and Rust samples stop. | Catch the error per search if one failed angle shouldn't stop the step. |
| A long session | Your agent loops many times. | Send the same `session_id` on every call to group the run. See [Group an agent run with a session ID](https://docs.keenable.ai/best-practices.md#group-an-agent-run-with-a-session-id). |

## Next steps

* [Split a broad question into parallel searches](https://docs.keenable.ai/best-practices.md#split-a-broad-question-into-parallel-searches): cap how many searches run at once.
* [Fact-check with citations](https://docs.keenable.ai/recipes/fact-check-with-citations.md): check the claims your research turns up.
* [RAG with fresh web results](https://docs.keenable.ai/recipes/rag-with-fresh-web-results.md): one search when the question is narrow.
* [Recipes](https://docs.keenable.ai/recipes.md): every recipe on one page.


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