---
name: "web_search"
area: "web"
title: "Search the web"
price: "$0.009"
method: "POST"
url: "https://api.conecto.chat/v1/tools/web_search"
mcp_server: "https://api.conecto.chat/mcp/web"
auth: "Authorization: Bearer <conecto_sk_ key>"
docs_url: "https://conecto.chat/tools/web/web_search"
---

# Search the web (`web_search`)

Searches the web through Conecto's own search service and returns each result's title, link, site and snippet.

Search the web through Conecto's own search service. Each result comes with its title, link, site and snippet; read a page in full with web_read. Narrow by country and language. $0.009 a search; a failed one costs nothing.

Price: $0.009 a call. A call that fails costs nothing.

## Use it when

The agent needs facts from the web: prices, opening hours, news, a company's site.

- For one page whose address you know, use [web_read](https://conecto.chat/tools/web/web_read.md).
- For a company's facts from its domain, use [lookup_company](https://conecto.chat/tools/lookups/lookup_company.md).

## Say this to your agent

> What do bike shops usually charge to ship a bike to Seattle?

## Inputs

| Name | Type | Required | Description | Allowed values | Default |
|---|---|---|---|---|---|
| `query` | string | yes | 1 to 256 characters. |  |  |
| `count` | integer | no | 1 to 20. |  | `10` |
| `country` | string | no | Exactly 2 characters. |  |  |
| `language` | string | no | Exactly 2 characters. |  |  |

## Example

Written for Halverson Cycle & Repair, a bike shop with a repair workshop in Portland, Oregon.

MCP: call `web_search` on the MCP server `https://api.conecto.chat/mcp/web` with these arguments:

```json
{
  "query": "bike shop shipping cost Seattle",
  "country": "US",
  "count": 5
}
```

REST:

```bash
curl https://api.conecto.chat/v1/tools/web_search \
  -H "Authorization: Bearer $CONECTO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "bike shop shipping cost Seattle", "country": "US", "count": 5}'
```

## Response

```json
{
  "call_id": "5f0c8a2e-3b7d-4c1e-9a64-2d8e1f7b0c93",
  "tool": "web_search",
  "status": "succeeded",
  "replayed": false,
  "cost_usd": "$0.009",
  "balance_usd": "$19.75",
  "result": {
    "query": "bike shop shipping cost Seattle",
    "results": [
      {
        "title": "Bike shipping cost to Seattle | Ridgeline Cycles",
        "url": "https://www.ridgeline-cycles.example/shipping",
        "site": "ridgeline-cycles.example",
        "snippet": "We ship built bikes anywhere in Washington, Seattle included, for $89. Boxing an e-bike costs $40 extra."
      },
      {
        "title": "Bike shipping in the US | Gravel Works",
        "url": "https://www.gravel-works.example/us/shipping",
        "site": "gravel-works.example",
        "snippet": "Shipping a bike to Seattle costs $129, and is free from $1,500."
      }
    ]
  }
}
```

`result`: query, and results: each with its title, url, site and snippet. Read a page in full with web_read.

## Errors

| Code | Status | When | Fix |
|---|---|---|---|
| `invalid_input` | 400 | The query is empty or over 256 bytes (about 250 letters), or country or language is not a two-letter code. | Shorten the query, and send country like US and language like en. |
| `rate_limited` | 429 | Too many searches at once. | Try again in a moment; nothing was charged. |
| `search_unavailable` | 503 | The search service is not available or did not answer. | Try again later; nothing was charged. |

The refusals every tool can give (401 key, 402 balance, 429 limits) are on the errors page: https://conecto.chat/docs/errors.md

## Related

- [web_read](https://conecto.chat/tools/web/web_read.md): Reads one public page and returns its main content as clean Markdown with its title, description and links; a PDF comes back as its text. $0.002 a call.