# Web search

> Search the web and get ranked pages with snippets, optionally with each page’s content or limited to one kind of page.

`web_search` searches the web and returns a ranked list of pages, each with a title, URL and a short snippet relevant to the query. Use it for current events, facts you’re unsure of, documentation, or finding sources to read.

Call it with `POST /v1/tools/web_search`, or as `web_search` over [MCP](https://clonvo.com/docs/mcp.md).

## Arguments

-   `query` string Required
    
    What to search for: a question or keywords.
    
-   `max_results` integer
    
    How many results to return (1–20, default 5).
    
-   `category` string
    
    Search only one kind of page. See [Categories](#categories).
    
    One of `news` `company` `people` `research_paper` `github` `pdf` `financial_report`
    
-   `include_domains` string\[\]
    
    Only return results from these domains, e.g. \["arxiv.org", "nature.com"\].
    
-   `exclude_domains` string\[\]
    
    Never return results from these domains.
    
-   `time_range` string
    
    Only return pages published within the last day, week, month or year.
    
    One of `day` `week` `month` `year`
    
-   `include_content` boolean
    
    Also return each result’s page content (markdown or plain text) in content, up to max_content_chars. Snippets stay at most 500 characters either way. Slower and costs more on some providers.
    
-   `max_content_chars` integer
    
    With include_content, the most characters of content to return per result (default 5,000).
    

## Example

```bash
curl https://api.clonvo.com/v1/tools/web_search \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": { "query": "PostgreSQL 18 release notes", "max_results": 3, "time_range": "year" }
  }'
```

```json
{
  "id": "gen-01M69T8V4J2QH3K5N7P9R1S3TX",
  "tool": "web_search",
  "provider": "clonvo",
  "result": {
    "query": "PostgreSQL 18 release notes",
    "results": [
      {
        "title": "PostgreSQL 18 Release Notes",
        "url": "https://www.postgresql.org/docs/18/release-18.html",
        "snippet": "Release date: 2025-09-25. This release contains a variety of fixes…",
        "published_at": "2025-09-25T00:00:00.000Z",
        "score": 0.86
      }
    ]
  },
  "usage": { "cost": 0.001, "charged": 0.00102, "is_byok": false }
}
```

## Result

| Field | Description |
| --- | --- |
| `query` | The query you sent. |
| `results[]` | The pages, best match first. |
| `results[].title`, `results[].url` | The page’s title and URL. |
| `results[].snippet` | A short excerpt relevant to the query, on one line, at most 500 characters, cut at a word with “…”. Can be empty. |
| `results[].content` | With `include_content`: the page text, up to `max_content_chars`. |
| `results[].published_at` | The page’s publication date (ISO 8601), when the provider returns one. |
| `results[].score` | A relevance score, when the provider returns one. Its scale depends on the provider. |
| `notes` | Present when the provider handled an argument differently. |

The fields around `result` (`id`, `tool`, `provider`, `usage`) are the same for every tool; see [Calling tools](https://clonvo.com/docs/calling-tools.md#response).

## Categories

| `category` | Searches |
| --- | --- |
| `news` | News articles |
| `company` | Company websites and profiles |
| `people` | LinkedIn-style professional profiles |
| `research_paper` | Research papers |
| `github` | Repositories and code on github.com |
| `pdf` | PDF documents |
| `financial_report` | Filings and financial reports |

Every category runs on Clonvo credits except `pdf`, which needs your own key for a provider that supports it. If none of your keys serves the category and Clonvo credits can’t either, the call fails with `tool_requires_own_key` and names the providers that can.

## Notes

-   Results can differ slightly between providers, for example in whether results have a date or a score. `notes` says when an argument was handled differently.
-   On Clonvo credits, each page `include_content` reads adds to the call’s cap; see [Tool billing](https://clonvo.com/docs/tool-billing.md#on-clonvo-credits).
-   Searches with category `people` or `company` are never stored as [web tool queries](https://clonvo.com/docs/privacy.md#web-tool-queries).