> ## 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 with operators: exact phrases, several sites, exclusions

> How to put quoted phrases, site:, OR, - and parentheses in a query, when to use them instead of the site and exclude_domains parameters, and the 400 fix.

Turn part of a query into a hard filter. Quote an exact error string, search several sites in one request, or leave a site or a phrase out, while the rest of the query stays a plain-language description that Keenable ranks by meaning.

## Parameters

| Parameter | In | Type | Default | Limits | What it does |
| - | - | - | - | - | - |
| `query` | Body, `/v1/search` | string | Required | None | What to search for, in plain language. It must contain search terms; operators such as `site:` alone return `400`, except that a query with only `site:` operators searches for the site name and adds a `warning`. |
| `site` | Body, `/v1/search` | string | None | None | Return results from one site only. Subdomains are included, and a path narrows further (`github.com/microsoft`). |
| `exclude_domains` | Body, `/v1/search` | array of strings | None | At most 2,000 entries | Never return results from these hosts. Each entry is a host name and also excludes every subdomain: `yahoo.com` also excludes `finance.yahoo.com`. |

The operators go inside `query`. [Search operators](https://docs.keenable.ai/api-reference/search.md#search-operators) in the API reference lists each one with its exact rules.

## Search two sites for an exact error string

This sample searches GitHub and Stack Overflow in one request for pages that contain the exact phrase `other side closed`, and prints the host and URL of each result. 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 results = await client.search(
    'connection pool timeout "other side closed" site:github.com OR site:stackoverflow.com',
    { maxResults: 5, snippetMaxLength: 180 },
  );
  for (const result of results) {
    console.log(new URL(result.url).hostname, result.url);
  }
}

main();
```

```python Python theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
from urllib.parse import urlsplit

from keenable import Keenable

client = Keenable()  # keyless: no API key needed to try it
results = client.search(
    'connection pool timeout "other side closed" site:github.com OR site:stackoverflow.com',
    max_results=5,
    snippet_max_length=180,
)
for result in results:
    print(urlsplit(result.url).hostname, result.url)
```

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

import (
	"context"
	"fmt"
	"log"
	"net/url"

	"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
	results, err := client.Search(context.Background(),
		`connection pool timeout "other side closed" site:github.com OR site:stackoverflow.com`,
		&keenable.SearchOptions{MaxResults: 5, SnippetMaxLength: &snippetCap})
	if err != nil {
		log.Fatal(err)
	}
	for _, result := range results.Results {
		host := ""
		if u, err := url.Parse(result.URL); err == nil {
			host = u.Hostname()
		}
		fmt.Println(host, 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(
            r#"connection pool timeout "other side closed" site:github.com OR site:stackoverflow.com"#,
            &SearchOptions {
                max_results: Some(5),
                snippet_max_length: Some(180),
                ..Default::default()
            },
        )
        .await?;
    for result in &results {
        let host = result.url.split('/').nth(2).unwrap_or_default();
        println!("{} {}", host, 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": "connection pool timeout \"other side closed\" site:github.com OR site:stackoverflow.com",
    "max_results": 5,
    "snippet_max_length": 180
  }'
```

You see 5 results, each on `github.com` or `stackoverflow.com`. This run was made on 19 November 2026:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
github.com https://github.com/github/copilot-cli/issues/3257
github.com https://github.com/nodejs/undici/issues/1415
stackoverflow.com https://stackoverflow.com/questions/76931498/typeerror-terminated-cause-socketerror-other-side-closed-in-fetch-nodejs?answertab=scoredesc
stackoverflow.com https://stackoverflow.com/questions/61076334/errors-shown-by-k6-when-reaching-a-bigger-number-of-virtual-users?rq=3
github.com https://github.com/openclaw/openclaw/issues/71784
```

`OR` binds only the two `site:` terms next to it, so `connection pool timeout` and the quoted phrase apply to both sites.

## Build a query

Start from a plain-language description, then add one operator per hard rule:

| You want | Add to the query | Example `query` |
| - | - | - |
| Pages with the exact wording | The words in quotes | `undici "other side closed"` |
| Pages on any of several sites | `site:` terms joined by `OR` | `keyboard reviews site:wired.com OR site:theverge.com` |
| Pages under one path of a site | `site:` with the path | `async runtime site:github.com/tokio-rs` |
| No pages from one site | `-site:` | `python 3.14 release notes -site:python.org` |
| No pages with a phrase | `-` before the quoted phrase | `postgres hosting comparison -"sponsored post"` |
| Either of two phrases inside a longer query | The alternatives in parentheses | `keyboard ("hall effect" OR "magnetic switch") review` |

A word with no operator is never a hard filter. To require a word, quote it.

## Operator or parameter

Some filters exist both as an operator and as a request parameter. Keep each kind of filter in one place:

| Filter | Use | Instead of |
| - | - | - |
| One site | The `site` parameter | `site:` in the query |
| Several sites | `site:a.com OR site:b.com` in the query | Several requests |
| Leave out one site | `-site:` in the query, or `exclude_domains` | Dropping results in your own code |
| Leave out a list of sites | The `exclude_domains` parameter, up to 1,000 distinct hosts | A long chain of `-site:` terms |
| Leave hosts out of one site | `site` with `exclude_domains` | `site` with `-site:` in the query |
| A date window | `published_after` and the other [date filters](https://docs.keenable.ai/guides/filter-by-date) | Dates in the query text |

See [Filter by domain](https://docs.keenable.ai/guides/filter-by-domain.md) for the `site` and `exclude_domains` parameters in depth.

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| `"query": "-site:reddit.com"` | Add search terms: `keyboard reviews -site:reddit.com` | A query of only operators returns `400` with `query must contain search terms, not only operators`. |
| `"query": "site:python.org"` | `release notes site:python.org` | A query of only `site:` terms searches for the site name and adds a `warning` to the response. |
| `site:wired.com or site:theverge.com` | `site:wired.com OR site:theverge.com` | `OR` and `NOT` work only in capitals. In lower case they're ordinary words. |
| `- site:reddit.com` | `-site:reddit.com` | A `-` with a space after it is read as a word, not an operator. |
| `"site": "python.org"` with `-site:docs.python.org` in the query | `"site": "python.org"` with `"exclude_domains": ["docs.python.org"]` | Put every site filter in one place. To leave hosts out of one site, send `exclude_domains` with `site`. |
| `react OR vue performance` to require one of two words | `("react" OR "vue") performance` | `OR` between plain words doesn't make them hard filters. Both stay descriptions that Keenable ranks by. |

A query that doesn't parse never fails. An unbalanced quote or parenthesis, or a dangling `OR`, is read as plain words, and the search still runs.

## In the SDKs, CLI and MCP

Operators are part of the query string, so every client takes them unchanged: the first argument of `search` in each SDK, the query argument of `keenable search` in the [CLI](https://docs.keenable.ai/cli.md), and `query` in the MCP tool `search_web_pages` (see [MCP server](https://docs.keenable.ai/mcp-server.md#available-tools)).

## API reference

* [Search operators](https://docs.keenable.ai/api-reference/search.md#search-operators): every operator and its rules.
* [Search request](https://docs.keenable.ai/api-reference/search.md#request): `query`, `site` and `exclude_domains` in full.
* [Write the query](https://docs.keenable.ai/best-practices.md#describe-the-page-you-want): describe the page you want before you add operators.


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