WebScrapingAPI Docs

Usage and troubleshooting

Understand automatic routing, product access, account usage, limits, and errors for the hosted Web MCP.

The hosted Web MCP uses your account's existing SERP API, Web Scraping API, and Browser API access. Your MCP token connects an agent to those services; it does not activate a product or add quota.

Which tools are available?

The server checks current product access when your client connects and on subsequent requests. Active access can include a valid trial. Your client discovers only the tools supported by that access.

Your account has access toAvailable toolsDefault page-reading service
SERP API onlyweb_searchNone
Web Scraping API onlyweb_read, web_read_moreWeb Scraping API
Browser API onlyweb_read, web_read_moreBrowser API
Web Scraping API and Browser APIweb_read, web_read_moreWeb Scraping API
SERP API and either reading serviceAll three toolsWeb Scraping API when available, otherwise Browser API

Without SERP API access, web_search is unavailable. An agent can still read a URL you provide if your account has a reading service. Adding an MCP token does not bypass the SERP API requirement.

An account without any supported product access cannot connect. If a product's quota is exhausted, its tool can still appear in discovery, but the API request returns a quota error. After changing product access or rotating a service API key, reconnect your MCP client to refresh the session and tool list.

Automatic routing

For a normal web_read call, the agent supplies a URL. The server selects Web Scraping API when your account has access to it; otherwise, it selects Browser API. Web Scraping API remains the default when you have both products.

An advanced caller can select an available service with the optional backend argument: "web-scraping-api" or "browser-api". The returned backend field records which service handled the page.

A failed request or exhausted quota does not automatically switch the request to another product. Selecting a different service requires an explicit new tool call and access to that service.

JavaScript rendering

Web Scraping API reads are static by default. If a page contains little useful text and depends on JavaScript, the agent can make another web_read call with render_js: true. This is a new fetch with normal product usage.

Browser API always renders JavaScript. Omit render_js or set it to true for Browser API; false is rejected before the API request. The rendering flag does not select a different service. A thin Browser API result has already been rendered, so repeating it just to enable JavaScript is unnecessary.

How usage is counted

ActionAccount usage
web_searchUses your SERP API allowance under its existing billing rules
web_read through Web Scraping APIUses your Web Scraping API credits under its existing billing rules
web_read through Browser APIUses your Browser API bandwidth allowance, including upload and download traffic
web_read_moreReads the stored capture; makes no additional API request or API charge

Browser API traffic is accounted for when its browser connection closes, so usage may not appear immediately. The search limit only caps the results returned to the agent; it does not change the API's billing rules.

Each new web_read fetches again, including repeated reads of the same URL and explicit retries with JavaScript rendering. These calls receive separate source IDs and use the selected product's normal metering. There are no automatic retries or rendering upgrades in the MCP adapter.

Cancelling a tool call stops its in-flight request where possible. It does not guarantee that usage already incurred is reversed. Disconnecting the client alone is not an explicit cancellation.

Limits and capture lifetime

LimitWhat it means for your agent
10 MiB downloaded HTML per pageOversized pages return an error
16 KiB serialized tool resultLarge readable pages arrive in chunks; use web_read_more for the rest
One-hour capture lifetimeFollow next_cursor promptly; captures can become unavailable earlier through cache eviction or a service restart
10 MiB stored captures per tokenEarlier captures may be evicted as new pages are read; storage is also subject to shared capacity
55-second upstream timeout; 60-second API client deadlineSet your MCP client's tool timeout above 60 seconds
Four concurrent tool calls per tokenLimit parallel work; underlying product and service capacity limits also apply
Four active sessions per tokenClose unused client connections before opening more
15 minutes idle or one hour per sessionThe client must initialize a new session after expiry
1,000 requests per sessionInitialize a new session when the request limit is reached

Captures are temporary, immutable snapshots. web_read_more continues the same snapshot and never silently fetches the page again. When a capture has expired or been evicted, make a new explicit web_read if you still need the page. That fetch can incur usage and may contain different content; do not combine it with old chunks as though they were one snapshot.

Use the exact source_id and next_cursor from the preceding result, passing next_cursor as the next call's cursor. Stop when next_cursor is null. Source IDs and cursors cannot be shared between MCP tokens.

Connection problems

SymptomWhat to check
HTTP 401 or an invalid-token messageUse the dedicated MCP token from Dashboard → MCP in the client's bearer-token field. Check for a revoked token or missing Bearer prefix when configuring the header yourself. A product API key is not an MCP token.
HTTP 403 or no active product accessCheck that the account has current SERP API, Web Scraping API, or Browser API access. If access changed, reconnect.
The client only offers OAuth sign-inUse a client that supports Streamable HTTP and custom bearer headers. OAuth-only clients are not supported.
A browser-based client reports an origin or CORS errorIts origin must be supported by the hosted endpoint. Contact support with the client name and origin; do not send your token.
HTTP 404 after a working connectionThe session may have expired or been invalidated by a service-key or access change. Reconnect and discover tools again.
HTTP 429Reduce parallel requests or close unused sessions, then retry later. If the message reports the session request limit, reconnect instead. Product rate limits can also apply.
HTTP 503 while authenticatingAuthorization is temporarily unavailable. Wait and reconnect.
Opening the endpoint in a browser returns HTTP 405The endpoint expects an MCP client using Streamable HTTP. It is not a webpage or a standalone event-stream URL.

Tokens are created and revoked by the account owner on MCP. A token is shown only once when created; if you lose it, revoke it and create another. Revocation blocks further requests, including continuation calls. Never paste a token or product API key into tool arguments, page URLs, source citations, or support messages.

Tool errors

ErrorNext step
INVALID_INPUT or a tool argument validation errorCheck the tool reference. Use a public HTTP(S) URL, a two-letter country code, and arguments supported by your chosen service.
ENTITLEMENT_DENIEDCheck access to the selected product or option. An optional backend override cannot enable a product.
AUTHENTICATION_FAILEDThe selected product rejected its service credential. Check the product's status in your dashboard and reconnect after any service-key change.
QUOTA_EXCEEDEDCheck the selected product's remaining allowance. The server will not automatically use another product's quota.
RATE_LIMITEDReduce concurrency and retry later. Respect a supplied retry_after_seconds value when present.
TIMEOUTThe API request exceeded its deadline. An explicit retry is a new request and can incur usage.
CANCELLEDThe call was cancelled. Retry only if the result is still needed.
UNSUPPORTED_CONTENTUse an HTML page with a supported text encoding. This tool does not extract text from downloads such as PDFs or images.
CONTENT_TOO_LARGESelect a smaller page or a more focused source.
UNREADABLE_PAGETry another source, or explicitly enable rendering for a Web Scraping API page that needs JavaScript.
SOURCE_EXPIREDThe capture is unavailable. Read the URL again explicitly if needed.
INVALID_CURSORPass the unchanged cursor returned for the same source and MCP token.
UPSTREAM_ERROR or INVALID_RESPONSEThe API request failed or returned unusable data. Retry explicitly if appropriate, or contact support if the issue persists.

A successful response with content_thin: true is a warning that little readable content was found, not evidence that the page answered the question. The agent should seek another source or, where appropriate, explicitly request rendering before writing a supported answer.

Return to getting started for connection setup, or use the tool reference for arguments and source metadata.

On this page