# Search the web

Returns the web pages that match a query, with title, address and snippet, a page at a time or up to 100 at once. Use it to find sources on a topic without picking a search engine.

Tool `web.search` on Open web and SEO. Contract version 1, released 2026-11-04.

## Example call

Over REST, send the input in the body. Over MCP, pass the same input to `call_tool`.

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/web.search/calls \
  -H "Authorization: Bearer $VOXORIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"query":"crm for small teams","country":"gb"}}'
```

Python:

```python
import os

import httpx

response = httpx.post(
    "https://api.voxoria.ai/v1/tools/web.search/calls",
    headers={"Authorization": f"Bearer {os.environ['VOXORIA_API_KEY']}"},
    json={"input": {"query": "crm for small teams", "country": "gb"}},
    timeout=60,
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/web.search/calls", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VOXORIA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"input": {"query": "crm for small teams", "country": "gb"}}),
});
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "call_tool",
  "arguments": {
    "tool": "web.search",
    "input": {
      "query": "crm for small teams",
      "country": "gb"
    }
  }
}
```

Both return [the full response](/docs/call-response.md): the call's ID, status and cost, with this tool's result in `output`.

## Input

| Input | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `query` | string | Yes |  | The search query. Search operators are supported: "exact phrase", -word, site:, -site:, filetype:, inurl:, allinurl:, intitle:, allintitle:, related:, imagesize: and larger:. 1 to 500 characters. |
| `country` | string | No | `us` | Two-letter ISO 3166-1 country code to localize results to. Case-insensitive. One of the 249 values of the `countries` list: ISO 3166-1 alpha-2 country codes, lowercase. |
| `language` | string | No |  | Two-letter ISO 639-1 language code of the results. Case-insensitive. Left out, the provider picks the country's main language. One of the 184 values of the `languages` list: ISO 639-1 two-letter language codes, lowercase. |
| `page` | integer | No | `1` | Page of results, about 10 per page. From 1 to 11. |
| `limit` | integer | No |  | Number of results to return, at most 100. Left out, about 10. From 1 to 100. |
| `time_range` | string | No |  | Only results from the last hour, day, week, month or year. One of `hour`, `day`, `week`, `month`, `year`. |
| `include_domains` | array of string | No |  | Only results from these sites, written as host names without scheme or path, such as reddit.com. Case-insensitive. Cannot be sent with exclude_domains. Each item: 1 to 253 characters. Each item: matches `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$`. 1 to 20 items. No item twice. |
| `exclude_domains` | array of string | No |  | No results from these sites, written as host names without scheme or path, such as reddit.com. Case-insensitive. Cannot be sent with include_domains. Each item: 1 to 253 characters. Each item: matches `^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$`. 1 to 20 items. No item twice. |

## Output

A successful call returns these blocks in its `output`. A field not marked required can be `null`.

### results

A list of rows. Always present, possibly empty.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `position` | integer | Yes | Rank among the results, starting at 1. |
| `title` | string | Yes |  |
| `url` | string | Yes |  |
| `snippet` | string | No | Text from the page that matches the query. Some providers send it as Markdown. |
| `site_name` | string | No | The name of the site, as the search engine shows it. Often its host name. |

## Example output

The `output` of a real call, each list cut to 3 items.

```json
{
  "results": [
    {
      "position": 1,
      "title": "CRM for a small team",
      "url": "https://www.reddit.com/r/CRM/comments/1dj7zku/crm_for_a_small_team/",
      "snippet": "Considering your team size and expectations, either Freshsales or Pipedrive will be your best option. Both have great UI. The starter plan is ...",
      "site_name": "www.reddit.com"
    },
    {
      "position": 2,
      "title": "The 7 best CRM systems for small businesses for 2026",
      "url": "https://startups.co.uk/crm-software/best-crm-for-small-business-uk/",
      "snippet": "Looking for the right CRM? We compare seven top CRM systems for small firms to match your sales, marketing, and support needs in 2026.",
      "site_name": "startups.co.uk"
    },
    {
      "position": 3,
      "title": "CRM Software for Small Business | Microsoft Dynamics 365",
      "url": "https://www.microsoft.com/en-us/dynamics-365/resources/crm-software-for-small-business",
      "snippet": "Designed for small teams, this CRM software is secure, cloud-based, and easy to set up—so you can focus less on systems and more on building lasting ...",
      "site_name": "www.microsoft.com"
    }
  ]
}
```