Tolca web-search: written guarantees for production use

Updated 2026-11-08

Tolca web-search runs a web search and reads the top result pages in the same paid call: POST https://tolca.tonbot.ca/v1/web-search, $0.008 per call in USDC on Base over x402, up to 5 pages and up to 50,000 characters of clean text per page (max_chars). This page lists what you can rely on in production, with the numbers we measured. Last measured: 2026-11-08.

1. Concurrency limit, and what happens beyond it

• Up to 8 searches can run at the same time, server-wide (all callers together).
• A 9th concurrent call gets HTTP 429 as soon as it reaches our server (within the same second): busy: 8 searches already running, retry in a few seconds (not charged). The payment is not settled, so you pay nothing. Retry after a few seconds. Time spent before the call reaches us, such as signing the payment on your side, adds to what your client measures.
• Measured with paid calls (read 5, max_chars 50,000): 9 calls sent at once gave 8 answers, all complete, in 4 to 13 seconds, and the 9th was refused in 0.5 s. The payer's USDC balance on Base went down by exactly 8 x $0.008.

2. Partial reads: a flag your code can gate on

Every response carries:

• complete: true when every available page you asked for was read.
• read_requested, read_available, read_returned: the counts behind that flag.
• pages_skipped: every page that could not be read, with the reason.

Send "require_complete": true to make the call all or nothing: if any available page cannot be read, the call returns HTTP 503 and is not charged. If you asked for pages and none could be read, the call returns HTTP 502 and is not charged.

3. Proof for every page

Each page in pages carries:

• fetched_at: when Tolca read the page (UTC).
• sha256: the hash of the exact text returned. Keep it with fetched_at to show later what the page said at that moment.
• url: the final address after redirects, and canonical: the canonical URL the page declares, when it declares one.
• published and modified: dates read from the page itself (meta tags, JSON-LD, time tags).

In results, age_source tells where each date came from: search (the search engine), page (the page's own publication date), page_modified (the page's own last-modified date), or null when no date was found.

4. Extraction versioning

extraction_version changes every time the way Tolca turns HTML into text changes. If a page has not changed, the same extraction_version and the same max_chars give the same text and the same sha256. Current version: 2026-11-08.

5. Measured latency

Paid calls, read 5, max_chars 50,000, time seen by the caller:

• 2 or 3 calls at once: 4.9 to 7.0 seconds each, all complete.
• 5 calls at once: 3.7 to 6.3 seconds each, all complete.
• 8 calls at once: 4.1 to 13.1 seconds each, all complete.

Each page gets 5 seconds. A slow or blocked page is skipped, listed in pages_skipped, and Tolca reads one extra result to replace it when it can.

6. Price you can read by machine, and when you pay

• The price is in the HTTP 402 answer (PAYMENT-REQUIRED header, x402 v2): amount 8000 = $0.008 in USDC on Base, the same price as in our public listings.
• Payment is settled only after a successful answer. No results (HTTP 404), no page read when pages were requested, an unmet require_complete, a 429, or any other error: not charged.
• If the settlement itself fails after the answer was built, you get HTTP 402 and you are not charged: retry the call.

Example

{ "query": "x402 payment protocol", "complete": true, "read_requested": 3, "read_available": 3, "read_returned": 3,
  "extraction_version": "2026-11-08",
  "pages": [{ "url": "https://...", "fetched_at": "2026-11-08T20:00:00.000Z", "sha256": "d0a1c149...",
              "published": "2026-09-02T00:00:00.000Z", "modified": null, "canonical": "https://..." }],
  "pages_skipped": [] }

Request format: OpenAPI. The same search is available as the web_search tool in our MCP server, with the same inputs, including max_chars and require_complete.