Web search API for AI agents: search and read the pages in one call

Updated 2026-10-18

The problem: "search the web" is rarely one step for an agent

When an AI agent needs a fact from the web, the usual pipeline looks like this:

1. Call a search API with a query and get a list of links and snippets.
2. Pick which links to open (usually the first few).
3. Fetch each page, which can be HTML, a PDF or JSON.
4. Strip menus, ads and scripts to keep the readable text.
5. Hand that text to the model, with some record of where it came from.

Each step is a separate tool call, often a separate vendor, a separate API key and a separate bill. For an autonomous agent, each extra call is also an extra place for something to fail. This guide shows the manual way first, then the one-call way.

The manual way (free or nearly free)

If you build this yourself, you need:

• A search source. Any search API or a self-hosted metasearch engine. Many have a free tier. Check each provider's current terms and limits yourself, because they change.
• A fetcher. A plain HTTP client works for simple pages. Pages that render with JavaScript need a headless browser, which is heavier to run.
• A text cleaner. A readability-style library that extracts the main content of an HTML page. PDFs need a separate extraction step.
• Provenance. If you want to prove later what the page said when your agent read it, store the URL, the fetch time and a hash of the content (for example SHA-256).
• Language and country handling. If your users are in Quebec or Canada, a generic English-first search often returns US results. Pass language and region parameters if your search source supports them.
• A rule for "official" answers. For questions about laws, permits, registries or court decisions, you want government and registry sites ahead of blogs. A simple allow-list of domains (for example .gouv.qc.ca, .gc.ca, canlii.org) is a reasonable start.

This works well if you have the time to maintain it. The cost is mostly engineering and upkeep, not money.

The one-call way: Tolca web-search

Tolca's web-search endpoint does the pipeline above in a single request:

• It returns 10 results with title, URL, snippet and date.
• It also returns the clean text of the best pages (you choose how many with read, from 0 to 5), each with the fetch time and a SHA-256 hash of the content.
• French and Canada by default when the query is in French.
• An official-sources mode (official) that favors governments, registries, courts and laws.
• A freshness filter and a site restriction (the site: idea, as a parameter).
• If there are no results, the API answers HTTP 404 and you are not charged.
• The price is $0.008 per call, paid per request.

Input fields: query (required), and optionally read, official, lang, country, freshness, site.

How payment works (x402)

There is no account and no API key. The flow is:

1. POST https://tolca.tonbot.ca/v1/web-search with your JSON body.
2. The server answers 402 Payment Required with the payment terms (x402 v2, USDC on Base).
3. Your x402-capable client pays and repeats the request with a payment signature header.
4. You receive the JSON result.

Any x402 client library can do steps 2 and 3 for you. The full description of the endpoint is in the OpenAPI file and in llms.txt.

Example request body

{
  "query": "licence RBQ exigée pour travaux de plomberie Québec",
  "read": 3,
  "official": true
}

Because the query is in French, the French and Canada defaults apply. With official set, the best pages read are the ones from government and registry sources when they are available.

For an English, UK-focused question you could pass lang and country explicitly instead of relying on defaults.

When one call is better, and when it is not

Good fit:

• An agent that needs a sourced answer to a factual question and has no human in the loop.
• Agents that need Quebec or Canadian sources in French.
• Cases where you want a fetch time and a content hash attached to every page read.
• Prototypes where you do not want to wire up three vendors before testing an idea.

Not a good fit:

• You need to crawl an entire website or thousands of pages. A crawler is the right tool.
• You need to log in to a site or interact with a page.
• You already run a search and scraping pipeline you are happy with.

Comparing with a search API plus a scraper

A common setup is one vendor for search and another for page extraction, so an agent makes at least two calls (usually more, one per page). The one-call approach folds this into a single request. Pricing and limits for other providers change often, so check their current pages before comparing costs. Tolca's price is the figure above: $0.008 per call.

Use it from an MCP client

Tolca also exposes its tools through MCP at https://tolca.tonbot.ca/mcp. The web_search tool is there alongside the other services. Payments go through the x402 payment header.

Related

• All guides: https://tolca.tonbot.ca/guides
• Checking a vendor before paying it: business verification (KYB) on Apify