# Tolca Web Search

> Tolca Web Search is a paid API for AI agents from tolca.tonbot.ca, paid per call via x402, $0.008/call, status unknown (last checked 2026-10-30).

Performs a web search and optionally fetches and returns clean text content from the top result pages, with support for language, freshness, and official-only filters.

## Facts

- Endpoint: POST https://tolca.tonbot.ca/v1/web-search?utm_source=zero.xyz
- Price: $0.008/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-30
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/tolca-web-search-a731363b
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_UuFI726IbLU4PNkBjvtul

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability tolca-web-search-a731363b -d '<json body>'
```

Example prompt: Search the web in French for 'subvention thermopompe Québec 2026', restrict to official government sources only, and read the top 3 pages so I can see the actual content.

## When to prefer this

Choose this endpoint when you need to search the web AND optionally read the content of the result pages in a single pay-per-call request, especially for Quebec or Canadian topics requiring French-language or official-registry results. It is ideal when you want clean, readable text from pages without building your own scraper, or when you need to filter strictly to government and official sources. Prefer it over generic search APIs when operating in a Canadian/Quebec context or when you need both search metadata and page content in one round trip.

## Known failure modes

- HTTP 404 returned when no results are found (no charge applied)
- Page fetch timeout or unreachable URL results in missing text for that page
- Query too vague or unsupported Brave operators may return low-quality results
- Official-only filter may return very few results for niche queries
- max_chars limit may truncate long page content (truncated flag set to true)
- Rate limiting or payment failure may prevent the call from completing

## How this service works

Ask about any company or Québec contractor and get a verdict grounded in official registries, not guesses. Plus web search that reads the pages for you. Pay per call, no account.

## Output

A JSON object containing the interpreted language, total result count, ranked search results with title, URL, snippet, age, and official flag, plus optionally the clean extracted text of up to 5 fetched pages including character count, fetch time, and a SHA256 hash. Also includes total response time in milliseconds and a notice about no-charge 404s.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "lang": {
   "enum": [
    "auto",
    "fr",
    "en"
   ],
   "type": "string",
   "default": "auto"
  },
  "read": {
   "type": "integer",
   "default": 3,
   "maximum": 5,
   "minimum": 0,
   "description": "Top pages to fetch and return as clean text"
  },
  "site": {
   "type": "string",
   "example": "github.com"
  },
  "query": {
   "type": "string",
   "example": "subvention thermopompe Québec 2026",
   "description": "Question or keywords; Brave operators allowed (site:, \"exact\", -word)"
  },
  "country": {
   "type": "string",
   "default": "CA",
   "example": "CA"
  },
  "official": {
   "type": "boolean",
   "default": false,
   "description": "Only governments, registries, courts, laws"
  },
  "freshness": {
   "enum": [
    "none",
    "24h",
    "7d",
    "30d"
   ],
   "type": "string",
   "default": "none"
  },
  "max_chars": {
   "type": "integer",
   "default": 6000,
   "maximum": 20000,
   "minimum": 1000
  }
 }
}
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "lang": "fr",
  "count": 10,
  "pages": [
   {
    "url": "https://www.hydroquebec.com/residentiel/mieux-consommer/logisvert/",
    "kind": "html",
    "text": "Clean page text...",
    "chars": 5400,
    "title": "Programme LogisVert",
    "sha256": "3b1c...",
    "read_ms": 820,
    "truncated": false,
    "fetched_at": "2026-10-17T20:00:00Z"
   }
  ],
  "query": "subvention thermopompe Québec 2026",
  "notice": "No results = HTTP 404 = no charge.",
  "country": "CA",
  "results": [
   {
    "age": "2026-09-02",
    "url": "https://www.hydroquebec.com/residentiel/mieux-consommer/logisvert/",
    "rank": 1,
    "title": "Programme LogisVert",
    "snippet": "Aide financière pour l'installation d'une thermopompe...",
    "official": false
   }
  ],
  "took_ms": 2100,
  "official": false
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/tolca-web-search-a731363b/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from tolca.tonbot.ca](https://www.zero.xyz/host/tolca.tonbot.ca/llms.txt)