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

# Filter web search results by domain

> How to search one site with site, leave hosts out with exclude_domains, and combine both, with the entry rules and the 400 invalid_filter fix.

Point your agent at the sources you trust and keep the rest out. Use `site` to search one site, `exclude_domains` to leave hosts out of an open search, and both together to search a site without some of its subdomains.

## Parameters

| Parameter | In | Type | Default | Limits | What it does |
| - | - | - | - | - | - |
| `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`. An empty array or `null` is the same as leaving it out. Results from excluded hosts are dropped, so fewer than `max_results` can come back. |

## Search one site without one of its subdomains

This sample searches `python.org` and every subdomain except the forum at `discuss.python.org`, and prints the top 5 results. 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
  const results = await client.search("asyncio TaskGroup exception handling", {
    site: "python.org", // python.org and its subdomains...
    excludeDomains: ["discuss.python.org"], // ...except the forum
    maxResults: 5,
  });
  for (const result of results) {
    console.log(result.title);
    console.log(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(
    "asyncio TaskGroup exception handling",
    site="python.org",  # python.org and its subdomains...
    exclude_domains=["discuss.python.org"],  # ...except the forum
    max_results=5,
)
for result in results:
    print(result.title)
    print(result.url)
```

```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() {
	client, err := keenable.New(nil) // keyless: no API key needed to try it
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	results, err := client.Search(context.Background(), "asyncio TaskGroup exception handling",
		&keenable.SearchOptions{
			Site:           "python.org",                   // python.org and its subdomains...
			ExcludeDomains: []string{"discuss.python.org"}, // ...except the forum
			MaxResults:     5,
		})
	if err != nil {
		log.Fatal(err)
	}
	for _, result := range results.Results {
		fmt.Println(result.Title)
		fmt.Println(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(
            "asyncio TaskGroup exception handling",
            &SearchOptions {
                site: Some("python.org".into()), // python.org and its subdomains...
                exclude_domains: Some(vec!["discuss.python.org".into()]), // ...except the forum
                max_results: Some(5),
                ..Default::default()
            },
        )
        .await?;
    for result in &results {
        println!("{}", result.title);
        println!("{}", 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": "asyncio TaskGroup exception handling",
    "site": "python.org",
    "exclude_domains": ["discuss.python.org"],
    "max_results": 5
  }'
```

You see results from `docs.python.org`, `peps.python.org` and `bugs.python.org`, none from `discuss.python.org`:

```text Example output · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
Issue 46752: Introduce task groups to asyncio and change task cancellation semantics
https://bugs.python.org/issue46752
Coroutines and tasks
https://docs.python.org/3.13/library/asyncio-task.html
PEP 654 – Exception Groups and except* | peps.python.org
https://peps.python.org/pep-0654
Futures
https://docs.python.org/3/library/asyncio-future.html
Exceptions
https://docs.python.org/3/library/asyncio-exceptions.html
```

The response is an ordinary search response. This excerpt is from the curl request above, with `max_results` set to 2 and `snippet_max_length` to 180:

```json Response excerpt · results vary theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "query": "asyncio TaskGroup exception handling",
  "mode": "pro",
  "results": [
    {
      "title": "Issue 46752: Introduce task groups to asyncio and change task cancellation semantics",
      "url": "https://bugs.python.org/issue46752",
      "description": "",
      "snippet": "subtasks can keep spawning more subtasks while __aexit__ is running; __aexit__ exits once the last subtask is done. I made this change after consulting some Trio folks, who knew",
      "acquired_at": "2026-11-07T05:01:49Z"
    }
  ]
}
```

Excluded results are dropped, not replaced, so fewer than `max_results` can come back. If `exclude_domains` covers the whole `site`, the response has no results.

## Write an entry

Each `exclude_domains` entry is a host. A host covers itself and every subdomain: `yahoo.com` also excludes `finance.yahoo.com`, while `blogs.un.org` excludes only `blogs.un.org` and its subdomains. Hosting domains such as `github.io` and `blogspot.com` count as hosts.

Keenable cleans up these slips and uses the host that is left: spaces around the entry, upper case, an `http://` or `https://` scheme, a leading `www.`, a port, a trailing `/` or dot, and a query string or fragment. So `https://WWW.UN.org/` becomes `un.org`.

| Limit | Value |
| - | - |
| Distinct hosts, after clean-up | 1,000 |
| Entries as sent | 2,000 |
| Length of one entry | 2,048 bytes |

## Search several sites

The `site` parameter takes one site. To search several, put `site:` operators in `query` and join them with `OR`:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"dark-plus"}}
{
  "query": "mechanical keyboard reviews site:wired.com OR site:theverge.com"
}
```

Keep every site filter in one place. Use the `site` parameter, or `site:` operators in the query, not both. See [Search operators](https://docs.keenable.ai/api-reference/search.md#search-operators), and the [Search operators guide](https://docs.keenable.ai/guides/search-operators.md) for grouping several sites with other terms.

## Common mistakes

| Wrong | Right | Why |
| - | - | - |
| `"exclude_domains": ["un.org/press"]` | `"exclude_domains": ["un.org"]` | An entry is a host. A path returns `400` with `invalid_filter`. |
| `"exclude_domains": ["*.python.org"]` | `"exclude_domains": ["python.org"]` | A host already covers its subdomains. A wildcard on a host returns `400` with `invalid_filter`. |
| `"exclude_domains": "pinterest.com"` | `"exclude_domains": ["pinterest.com"]` | Over HTTP the value is an array. A string returns `400` with `"exclude_domains": must be an array of strings`. |
| `"site": "python.org"` with `-site:discuss.python.org` in `query` | `"site": "python.org"` with `"exclude_domains": ["discuss.python.org"]` | Don't mix the `site` parameter with `site:` operators. Use `exclude_domains` to remove hosts inside a site. |
| A long `exclude_domains` list on `GET /v1/search` | The same list in a `POST` body | The URL length caps a GET at a few hundred hosts. A longer URL fails before it reaches the API. |

A rejected entry returns `400` with `error` set to `invalid_filter`. The `value` field holds the entry as you sent it and `reason` says what to change. See [Rejected entries](https://docs.keenable.ai/api-reference/search.md#rejected-entries).

## In the SDKs, CLI and MCP

The SDKs take `exclude_domains` in Python and Rust, `excludeDomains` in TypeScript (from `keenable` 0.2.0) and `ExcludeDomains` in Go. The CLI takes `--site` and `--exclude-domain`, which you repeat or give a comma list (see [CLI](https://docs.keenable.ai/cli.md)). Over MCP, `search_web_pages` takes `site` and `exclude_domains` (see [MCP server](https://docs.keenable.ai/mcp-server.md#available-tools)).

## API reference

* [Exclude domains](https://docs.keenable.ai/api-reference/search.md#exclude-domains): what an entry matches, clean-up, limits and GET requests.
* [Search request](https://docs.keenable.ai/api-reference/search.md#request): `site` and `exclude_domains` in full.
* [Filter by date](https://docs.keenable.ai/guides/filter-by-date): add a date window to a site search.


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