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

# Choose a search mode: pro or realtime

> How to pick pro for deeper retrieval or realtime for the fastest response, set the mode in each client, and check which mode served a call.

Pick the search mode that fits your agent's time budget. Leave `mode` at `pro` for deeper retrieval, and switch to `realtime` when response time matters more than depth, such as in a voice agent that searches while the user waits.

## Parameters

| Parameter | In | Type | Default | Limits | What it does |
| - | - | - | - | - | - |
| `mode` | Body, `/v1/search` | string | Your organization's default mode (`pro` unless changed) | One of `pro`, `realtime` | How hard to search: `pro` (default) for deeper retrieval and the best ranking, `realtime` for the fastest response. Each mode is billed as its own SKU (`search.pro`, `search.realtime`). If you leave it out, your organization's default mode applies, which is `pro` unless changed. |

## Compare the two modes

| | `pro` | `realtime` |
| - | - | - |
| What you get | Deeper retrieval | The fastest response |
| Use it for | Research, multi-step agents, answers you cite | Voice agents, chat turns with a tight latency budget |
| Billed as | `search.pro` | `search.realtime` |
| Works without an API key | Yes | Yes, over HTTP and the SDKs |
| Filters, operators, `safety_mode`, `disable_cards` | Yes | Yes |

Both SKUs cost the same at standard prices. See [Pricing](https://docs.keenable.ai/pricing.md).

## Time both modes on your own queries

This sample runs the same query in each mode and prints the mode that served the call, the number of results and the time it took. It runs with no API key:

```typescript TypeScript theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
import { Keenable } from "keenable";

async function main() {
  const client = new Keenable(); // keyless: no API key needed to try it
  const query = "current weather warnings for Lisbon";

  for (const mode of ["pro", "realtime"] as const) {
    const start = performance.now();
    const results = await client.search(query, { mode, maxResults: 3, snippetMaxLength: 200 });
    const elapsedMs = performance.now() - start;
    console.log(`${results.mode}: ${results.length} results in ${elapsedMs.toFixed(0)} ms`);
  }
}

main();
```

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

from keenable import Keenable

client = Keenable()  # keyless: no API key needed to try it
query = "current weather warnings for Lisbon"

for mode in ("pro", "realtime"):
    start = time.perf_counter()
    results = client.search(query, mode=mode, max_results=3, snippet_max_length=200)
    elapsed_ms = (time.perf_counter() - start) * 1000
    print(f"{results.mode}: {len(results)} results in {elapsed_ms:.0f} ms")
```

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

import (
	"context"
	"fmt"
	"log"
	"time"

	"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()

	query := "current weather warnings for Lisbon"
	snippetCap := 200
	for _, mode := range []string{"pro", "realtime"} {
		start := time.Now()
		results, err := client.Search(context.Background(), query,
			&keenable.SearchOptions{Mode: mode, MaxResults: 3, SnippetMaxLength: &snippetCap})
		if err != nil {
			log.Fatal(err)
		}
		served := mode
		if results.Mode != nil {
			served = *results.Mode
		}
		fmt.Printf("%s: %d results in %d ms\n", served, len(results.Results), time.Since(start).Milliseconds())
	}
}
```

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

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 query = "current weather warnings for Lisbon";

    for mode in ["pro", "realtime"] {
        let start = Instant::now();
        let results = client
            .search_with(
                query,
                &SearchOptions {
                    mode: Some(mode.into()),
                    max_results: Some(3),
                    snippet_max_length: Some(200),
                    ..Default::default()
                },
            )
            .await?;
        let served = results.mode.as_deref().unwrap_or(mode);
        println!(
            "{}: {} results in {} ms",
            served,
            results.results.len(),
            start.elapsed().as_millis()
        );
    }
    Ok(())
}
```

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
for mode in pro realtime; do
  curl -s -w '\n%{time_total}' \
    -X POST https://api.keenable.ai/v1/search/public \
    -H "Content-Type: application/json" \
    -H "X-Keenable-Title: My App" \
    -d "{\"query\": \"current weather warnings for Lisbon\", \"mode\": \"$mode\", \"max_results\": 3, \"snippet_max_length\": 200}" |
    jq -rn --arg asked "$mode" 'input as $r | input as $secs |
      if $r.results then "\($r.mode): \($r.results | length) results in \($secs * 1000 | round) ms"
      else "\($asked) failed: \($r.error // $r)" end'
done
```

You see one line per mode:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
pro: 3 results in <n> ms
realtime: 3 results in <n> ms
```

Times depend on the query and on the network between your code and the API, so measure from where your agent runs. The response's `mode` field names the mode that served the call. The curl sample reads it with `jq` and prints the API's error message when a call fails. This is the body of the same curl request with `mode` set to `realtime`, `max_results` to 1 and `snippet_max_length` to 180:

```json Response · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "query": "current weather warnings for Lisbon",
  "mode": "realtime",
  "results": [
    {
      "title": "Lisbon, Lisboa, Portugal Weather Advisories - Warnings & Watches | AccuWeather",
      "url": "https://accuweather.com/en/pt/lisbon/274087/weather-warnings/274087",
      "description": "",
      "snippet": "The following official weather warnings and advisories are currently in effect for Lisbon, issued by Portuguese Institute for the Sea and the Atmosphere. AccuWeather aggregates",
      "acquired_at": "2026-11-18T15:31:02Z"
    }
  ]
}
```

## Know which mode applies

If you leave `mode` out, the mode that applies depends on the client:

| Client | Mode when you leave it out |
| - | - |
| HTTP API | Your organization's default mode, which is `pro` unless changed |
| Python, TypeScript, Go and Rust SDKs | `pro`. Each SDK sends `pro` when you don't set a mode. |
| CLI | `default_search_mode` from `keenable config`, then your organization's mode, then `pro`. A `forced_search_mode` in `keenable config` overrides both `--mode` and `default_search_mode`. |
| MCP server | The mode the model passes to `search_web_pages`. If the model leaves it out, the `default_search_mode` query parameter on the server URL, then your organization's default mode. On `/mcp-public`, the tool doesn't offer `mode`. |

Set the mode in each language's style: `mode="realtime"` in Python, `{ mode: "realtime" }` in TypeScript, `Mode: "realtime"` in Go, `mode: Some("realtime".into())` in Rust and `--mode realtime` in the CLI.

## Voice agents

A voice agent searches while the user waits for a spoken answer, so use `realtime`. In Pipecat, `KeenableWebSearch` uses `realtime` by default when you pass an API key. See [Pipecat](https://docs.keenable.ai/integrations/pipecat.md#pick-a-search-mode).

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| `"mode": "fast"` | `"mode": "realtime"` | The API returns `400` with `"mode": is not a supported search mode; use "pro" or "realtime"`. |
| `"mode": "Realtime"` | `"mode": "realtime"` | Modes are lower case. The API returns `400` and asks whether you meant `realtime`. |
| Leave `mode` out of an HTTP call and expect `pro` | Send `"mode": "pro"` | Without it, your organization's default mode applies. |
| Expect a `mode` argument on `/mcp-public` | Use `https://api.keenable.ai/mcp` with an API key | `/mcp-public` doesn't list `mode`. See [MCP server](https://docs.keenable.ai/mcp-server.md#keyless-endpoint-for-listings-and-presets). |

## API reference

* [Search request](https://docs.keenable.ai/api-reference/search.md#request): `mode` and every other parameter.
* [Balance and usage](https://docs.keenable.ai/credits.md#what-a-call-costs): how `search.pro` and `search.realtime` are reported.
* [Search, then fetch](https://docs.keenable.ai/guides/search-then-fetch.md): keep each turn small once you've picked a mode.


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