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

# Search the web, then fetch the pages you need

> How to answer from search snippets first, fetch a page only when a snippet falls short, ask fetch for only the part you need, and when to set live=true.

Give your agent the facts it needs with the fewest characters in its context. Search with short snippets first. Answer from the snippets when they hold the answer, and fetch a page only when they don't, asking fetch for only the part you need.

## Parameters

| Parameter | In | Type | Default | Limits | What it does |
| - | - | - | - | - | - |
| `query` | Body, `/v1/search` | string | Required | None | What to search for, in plain language. |
| `max_results` | Body, `/v1/search` | integer | `10` | 1 to 50 | Maximum number of results to return. Fewer come back if fewer pages match. |
| `snippet_max_length` | Body, `/v1/search` | integer | None | 180 to 10,000 | Maximum characters of page text in each result's `snippet`. Without it, snippets can run to several thousand characters. |
| `url` | Query, `/v1/fetch` | string | Required | None | The page to read, as an absolute `http` or `https` URL. URL-encode it when it has its own query string. |
| `max_chars` | Query, `/v1/fetch` | integer | `50000` | At least 1 | Maximum number of characters of `content`, counted in Unicode code points. |
| `live` | Query, `/v1/fetch` | boolean | `false` | None | Set to `true` to fetch the page from the source now instead of returning Keenable's indexed copy. Without it, Keenable returns its indexed copy if it has a usable one and fetches the page live otherwise. A call that fetched live is billed as `fetch.live`. |
| `prompt` | Query, `/v1/fetch` | string | None | At most 2,000 characters | An instruction for extracting part of the page, at most 2000 characters. When set, a model reads the page and `content` holds only its answer instead of the whole page. |

## Search, then fetch the top result

This sample searches with 300-character snippets, takes the top result, and fetches only the answer to a question about that page. 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";

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

  // 1. Search with short snippets, enough to pick a page
  const results = await client.search("official Python documentation for asyncio TaskGroup", {
    maxResults: 3,
    snippetMaxLength: 300,
  });
  const top = results.results[0];
  console.log(`Top result: ${top.title} (${top.url})`);

  // 2. Fetch only that page, and only the part you need
  const page = await client.fetch(top.url, {
    prompt: "What happens to the other tasks when one task in a TaskGroup raises? Answer in two sentences.",
    maxChars: 600,
  });
  console.log(page.content);
}

main();
```

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

client = Keenable()  # keyless: no API key needed to try it

# 1. Search with short snippets, enough to pick a page
results = client.search(
    "official Python documentation for asyncio TaskGroup",
    max_results=3,
    snippet_max_length=300,
)
top = results[0]
print(f"Top result: {top.title} ({top.url})")

# 2. Fetch only that page, and only the part you need
page = client.fetch(
    top.url,
    prompt="What happens to the other tasks when one task in a TaskGroup raises? Answer in two sentences.",
    max_chars=600,
)
print(page.content)
```

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

import (
	"context"
	"fmt"
	"log"

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

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 with short snippets, enough to pick a page
	snippetCap := 300
	results, err := client.Search(ctx, "official Python documentation for asyncio TaskGroup",
		&keenable.SearchOptions{MaxResults: 3, SnippetMaxLength: &snippetCap})
	if err != nil {
		log.Fatal(err)
	}
	if len(results.Results) == 0 {
		log.Fatal("no results")
	}
	top := results.Results[0]
	fmt.Printf("Top result: %s (%s)\n", top.Title, top.URL)

	// 2. Fetch only that page, and only the part you need
	page, err := client.FetchWithOptions(ctx, top.URL, &keenable.FetchOptions{
		Prompt:   "What happens to the other tasks when one task in a TaskGroup raises? Answer in two sentences.",
		MaxChars: 600,
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(page.Content)
}
```

```rust Rust theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
use keenable::{Client, FetchOptions, SearchOptions};

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

    // 1. Search with short snippets, enough to pick a page
    let results = client
        .search_with(
            "official Python documentation for asyncio TaskGroup",
            &SearchOptions {
                max_results: Some(3),
                snippet_max_length: Some(300),
                ..Default::default()
            },
        )
        .await?;
    let top = &results.results[0];
    println!("Top result: {} ({})", top.title, top.url);

    // 2. Fetch only that page, and only the part you need
    let page = client
        .fetch_with(
            &top.url,
            &FetchOptions {
                prompt: Some(
                    "What happens to the other tasks when one task in a TaskGroup raises? Answer in two sentences."
                        .into(),
                ),
                max_chars: Some(600),
                ..Default::default()
            },
        )
        .await?;
    println!("{}", page.content);
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
# 1. Search with short snippets, enough to pick a page, and take the top result
url=$(curl -s -X POST https://api.keenable.ai/v1/search/public \
  -H "Content-Type: application/json" \
  -H "X-Keenable-Title: My App" \
  -d '{
    "query": "official Python documentation for asyncio TaskGroup",
    "max_results": 3,
    "snippet_max_length": 300
  }' | jq -r '.results[0].url // empty')

if [ -z "$url" ]; then
  echo "No results"
else
  echo "Top result: $url"
  # 2. Fetch only that page, and only the part you need
  curl -s -G https://api.keenable.ai/v1/fetch/public \
    -H "X-Keenable-Title: My App" \
    --data-urlencode "url=$url" \
    --data-urlencode "prompt=What happens to the other tasks when one task in a TaskGroup raises? Answer in two sentences." \
    --data-urlencode "max_chars=600"
fi
```

You see the page the search picked, then a two-sentence answer from that page instead of the whole page:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
Top result: Coroutines and Tasks (https://docs.python.org/3.11/library/asyncio-task.html?highlight=asyncio%20sleep)
The remaining tasks in the group are cancelled. No further tasks can then be added to the group.
```

The curl tab takes the top result URL with `jq`. The fetch response holds the extraction in `content`. This is an example fetch response:

```json Response · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "url": "https://docs.python.org/3/library/asyncio-task.html",
  "title": "Coroutines and tasks",
  "content": "When one task in a TaskGroup raises an exception (other than `asyncio.CancelledError`), the remaining tasks in the group are cancelled. No further tasks can then be added to the group.",
  "description": "",
  "truncated": false,
  "total_chars": 184
}
```

## Decide when to fetch

Each search result's `snippet` is page text chosen for the query, so it often holds the answer. Fetch when one of these is true:

| Situation | What to send |
| - | - |
| The snippets hold the answer | Nothing more. Answer and cite the result URLs. |
| A snippet is close but cut off | Fetch that URL with a `prompt` that asks for the missing part. |
| You need exact wording, such as a quotation or a config block | Fetch that URL without a `prompt`, and set `max_chars` to what your context can hold. |
| The user names a URL | Fetch it directly. You don't need a search first. |
| The page changes often, such as a status page or a price list | Fetch with `live=true`. |

## Fetch the current version of a page

By default, fetch returns Keenable's indexed copy of the page if it has a usable one, and fetches the page from the source otherwise. Set `live=true` when the indexed copy may be out of date for your task. Compare the search result's `acquired_at`, when Keenable indexed the page, with how often the page changes.

A call that fetched from the source is billed as `fetch.live`, whether you set `live=true` or Keenable had no indexed copy. Read `usage.sku` in a keyed response to see which one you paid for. See [Fetch](https://docs.keenable.ai/products/fetch.md#cost) and [Live fetch](https://docs.keenable.ai/guides/live-fetch.md).

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| Fetch every search result | Read the snippets, then fetch only the pages they don't answer | Each fetch adds a full page to the context and is billed on its own. |
| Fetch a long page with no limit | Add a `prompt`, or set `max_chars` | Without them, `content` can hold up to 50,000 characters. |
| `live=true` on every fetch | `live=true` only for pages that change often | Every live call is billed as `fetch.live`. The indexed copy answers most questions. |
| Read the result's `description` | Read `snippet` on a search result and `content` on a fetch | `description` is deprecated and always empty. See [Versioning](https://docs.keenable.ai/versioning.md). |
| `url=https://example.com/a?b=1&c=2` pasted into a query string | URL-encode it, for example with `curl --data-urlencode` | An unencoded `&` splits the URL into separate parameters. |

When `content` is cut at `max_chars`, `truncated` is `true` and `total_chars` holds the full length. Fetch again with a larger `max_chars`, or with a `prompt`, if you need the rest. See [Read long pages](https://docs.keenable.ai/guides/long-pages.md) and [Fetch with a prompt](https://docs.keenable.ai/guides/fetch-with-prompt.md).

## In the SDKs, CLI and MCP

`fetch` takes `max_chars`, `live` and `prompt` in every SDK: keyword arguments in Python, `fetch(url, { maxChars, live, prompt })` in TypeScript (from `keenable` 0.2.0), `FetchWithOptions` with `FetchOptions` in Go, and `fetch_with` with `FetchOptions` in Rust. See [SDK methods](https://docs.keenable.ai/sdks.md#methods). Over MCP, `fetch_page_content` takes the same three arguments and returns at most 20,000 characters unless you set `max_chars` (see [MCP server](https://docs.keenable.ai/mcp-server.md#available-tools)).

## API reference

* [Fetch API reference](https://docs.keenable.ai/api-reference/fetch.md): every fetch parameter and response field.
* [Search API reference](https://docs.keenable.ai/api-reference/search.md): `max_results`, `snippet_max_length` and the result fields.
* [Ground answers with citations](https://docs.keenable.ai/guides/ground-answers-with-citations.md): turn the snippets you keep into a cited prompt.


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