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

# Control the size of web search results

> How to set max_results (1 to 50) and snippet_max_length (180 to 10,000) so search results fit your context, and when to send disable_cards for web pages only.

Decide how much text a search puts in your agent's context before you send it. `max_results` sets how many results come back, `snippet_max_length` caps the page text in each one, and `disable_cards` keeps every result an ordinary web page.

## Parameters

| Parameter | In | Type | Default | Limits | What it does |
| - | - | - | - | - | - |
| `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. |
| `disable_cards` | Body, `/v1/search` | boolean | `false` | None | Set to `true` to leave cards (results at `https://cards.keenable.ai/w/<id>` that Keenable writes for queries such as prices or company facts) out of the results; ordinary web pages take their place. |

A search costs the same whether it returns 1 result or 50. See [Pricing](https://docs.keenable.ai/pricing.md#what-each-call-costs).

## Search with a fixed size and no cards

This sample asks for 3 results with snippets of at most 180 characters and no cards, then prints each URL with the length of its snippet. 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 for disableCards.
import { Keenable } from "keenable";

async function main() {
  const client = new Keenable(); // keyless: no API key needed to try it
  const results = await client.search("bitcoin price in USD", {
    maxResults: 3, // at most 3 results
    snippetMaxLength: 180, // at most 180 characters of page text each
    disableCards: true, // web pages only, no cards.keenable.ai results
  });
  for (const result of results) {
    console.log([...result.snippet].length, result.url);
  }
}

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
results = client.search(
    "bitcoin price in USD",
    max_results=3,  # at most 3 results
    snippet_max_length=180,  # at most 180 characters of page text each
    disable_cards=True,  # web pages only, no cards.keenable.ai results
)
for result in results:
    print(len(result.snippet), result.url)
```

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

import (
	"context"
	"fmt"
	"log"
	"unicode/utf8"

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

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

	snippetCap := 180 // at most 180 characters of page text each
	results, err := client.Search(context.Background(), "bitcoin price in USD", &keenable.SearchOptions{
		MaxResults:       3, // at most 3 results
		SnippetMaxLength: &snippetCap,
		DisableCards:     true, // web pages only, no cards.keenable.ai results
	})
	if err != nil {
		log.Fatal(err)
	}
	for _, result := range results.Results {
		fmt.Println(utf8.RuneCountInString(result.Snippet), result.URL)
	}
}
```

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

#[tokio::main]
async fn main() -> Result<(), keenable::Error> {
    let client = Client::new()?; // keyless: no API key needed to try it
    let results = client
        .search_with(
            "bitcoin price in USD",
            &SearchOptions {
                max_results: Some(3),          // at most 3 results
                snippet_max_length: Some(180), // at most 180 characters of page text each
                disable_cards: true,           // web pages only, no cards.keenable.ai results
                ..Default::default()
            },
        )
        .await?;
    for result in &results {
        println!("{} {}", result.snippet.chars().count(), result.url);
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
curl -X POST https://api.keenable.ai/v1/search/public \
  -H "Content-Type: application/json" \
  -H "X-Keenable-Title: My App" \
  -d '{
    "query": "bitcoin price in USD",
    "max_results": 3,
    "snippet_max_length": 180,
    "disable_cards": true
  }'
```

You see 3 web pages, each snippet at most 180 characters long. This run was made on 19 November 2026:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
174 https://coingecko.com/en/coins/bitcoin
93 https://finance.yahoo.com/quote/BTC-USD/history
153 https://coinbase.com/converter/wld
```

## Cards and disable\_cards

For queries such as prices, exchange rates or facts about a company, Keenable can write a result itself: a card. A card's `url` starts with `https://cards.keenable.ai/w/` and works for one day. This result is from the same request without `disable_cards`:

```json Response excerpt · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "title": "Bitcoin (BTC) to USD conversion rate: Exchange rate from Bitcoin (BTC) to United States Dollar (USD).",
  "url": "https://cards.keenable.ai/w/01a1f3cb-38ae-7292-83cb-e632038c78ce",
  "description": "",
  "snippet": "\nExchange rate from Bitcoin (BTC) to United States Dollar (USD). The current rate is $63,716 per BTC. The rate fell 0.8865% (569.894 USD) over the past day, from Nov 18, 2026",
  "published_at": "2026-11-19T12:32:24Z",
  "acquired_at": "2026-11-19T12:32:24Z"
}
```

With `disable_cards: true`, an ordinary web page takes the card's place, so you still get the same number of results. Send it when your code stores URLs, cites them after a day, or must cite the original publisher.

## Pick the sizes

Start from the job, then tune with what your agent's context can hold:

| Job | `max_results` | `snippet_max_length` |
| - | - | - |
| Pick one page to fetch | 3 to 5 | 180 to 300 |
| Answer from snippets with citations | 5 to 10 | 500 to 1,000 |
| Survey a topic broadly | 20 to 50 | 180 to 300 |
| Read one source in depth without a fetch | 1 to 3 | 2,000 to 10,000 |

If you leave `snippet_max_length` out, snippets can run to several thousand characters each, and 10 results come back. Set both on every search an agent makes.

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| `"snippet_max_length": 100` | A value from 180 to 10000 | The API returns `400` with `"snippet_max_length": must be an integer between 180 and 10000`. |
| `"max_results": 100` | A value from 1 to 50, or several narrower searches | The API returns `400` with `"max_results": must be an integer between 1 and 50`. |
| Expect exactly `max_results` results | Handle fewer | Fewer come back when fewer pages match, or when `exclude_domains` drops some. |
| `disable_cards` with `safety_mode` | One or the other | The API returns `400` with code `invalid_parameter`. See [safety\_mode](https://docs.keenable.ai/api-reference/search.md#request). |
| Cite a card URL in a stored report | Send `disable_cards: true`, or cite within a day | A card URL stops working after one day. |

## In the SDKs, CLI and MCP

| Parameter | Python | TypeScript | Go | Rust | CLI |
| - | - | - | - | - | - |
| `max_results` | `max_results` | `maxResults` | `MaxResults` | `max_results` | `--max-results` |
| `snippet_max_length` | `snippet_max_length` | `snippetMaxLength` | `SnippetMaxLength` | `snippet_max_length` | `--snippet-max-length` |
| `disable_cards` | `disable_cards` | `disableCards`, from `keenable` 0.2.0 | `DisableCards` | `disable_cards` | Not available |

Over MCP, `search_web_pages` takes all three (see [MCP server](https://docs.keenable.ai/mcp-server.md#available-tools)). To size the prompt block you build from the results, see [Control context size](https://docs.keenable.ai/best-practices.md#control-context-size).

## API reference

* [Search request](https://docs.keenable.ai/api-reference/search.md#request): `max_results`, `snippet_max_length` and `disable_cards` in full.
* [Search, then fetch](https://docs.keenable.ai/guides/search-then-fetch.md): read snippets first and fetch only what they miss.
* [Ground answers with citations](https://docs.keenable.ai/guides/ground-answers-with-citations.md): turn the results into a cited prompt.


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