ReadFetch

readfetch_residential

Read-only

Identical request and response to /v1/scrape, but the render leaves through a residential address instead of the datacentre. For targets that block by IP reputation (DataDome, PerimeterX, Cloudflare, AWS WAF). One attempt, no retries: residential bandwidth is the cost, and four times the scrape price is what it takes to cover it honestly. Prefer readfetch_scrape when datacentre egress works; use readfetch_residential only after readfetch_scrape fails or readfetch_probe reports a persistent challenge.

Input Schema

Name	Required	Description	Default
`url`	Yes	Public http(s) URL to load in Chromium.
`auth`	No	Optional cookie, bearer, or basic auth for the page load.
`mode`	No	Whole-call budget and render depth: fast (15 s), render (30 s, default), or full (60 s with page scroll).	render
`fresh`	No	When true, bypass cached scrape results (default false).
`format`	No	Primary body field returned: markdown (default), plain text, or raw HTML.	markdown
`options`	No	Deprecated — use `advanced` instead (same ScrapeOptions shape). Scheduled for removal in a future API semver bump.
`advanced`	No	Browser interactions: scroll, wait_for selector, js_code, headers, cookies, locale, include_links, etc.

Output Schema

Name	Required	Description	Default
`url`	No
`title`	No
`billed`	No
`status`	No
`markdown`	No
`status_code`	No
`cache_status`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed21 schema fields changedNov 1, 2026

addedInput schema / $defs / Auth / properties / cookies / description

Added value: +"Cookie jar when `type` is cookie; ignored for bearer/basic."

addedInput schema / $defs / Auth / properties / password / description
```
Added value: +"Basic-auth password when `type` is basic."
```

addedInput schema / $defs / Auth / properties / token / description

Added value: +"Bearer token when `type` is bearer (Authorization: Bearer …)."

addedInput schema / $defs / Auth / properties / type / description

Added value: +"Authentication mode: `cookie` (set `cookies`), `bearer` (set `token`), or `basic` (set `username` and `password`)."

addedInput schema / $defs / Auth / properties / username / description
```
Added value: +"Basic-auth username when `type` is basic."
```
addedInput schema / $defs / Cookie / properties / domain / description
```
Added value: +"Optional domain scope, e.g. `.example.com`."
```
addedInput schema / $defs / Cookie / properties / name / description
```
Added value: +"Cookie name."
```
addedInput schema / $defs / Cookie / properties / path / description
```
Added value: +"Path scope within the domain (default `/`)."
```

addedInput schema / $defs / Cookie / properties / url / description

Added value: +"Optional full URL scope for the cookie; alternative to `domain`/`path`."

addedInput schema / $defs / Cookie / properties / value / description
```
Added value: +"Cookie value."
```
addedInput schema / $defs / ScrapeOptions / properties / cookies / description
```
Added value: +"Inject cookies without `auth`; same shape as auth cookies."
```

addedInput schema / $defs / ScrapeOptions / properties / delay_before_return_ms / description

Added value: +"Pause after navigation before snapshot (0–60000, default 0); use for short post-load animations."

addedInput schema / $defs / ScrapeOptions / properties / headers / description

Added value: +"Extra HTTP request headers for the navigation (merged with defaults)."

addedInput schema / $defs / ScrapeOptions / properties / include_html / description

Added value: +"When true, include raw HTML in the response in addition to the primary `format` field."

addedInput schema / $defs / ScrapeOptions / properties / include_links / description

Added value: +"When true, add a `links` array (href/text) alongside the main body."

addedInput schema / $defs / ScrapeOptions / properties / js_code / description

Added value: +"JavaScript executed in the page before extraction; one string or an array run in order. Disables shared-browser cache for this call."

addedInput schema / $defs / ScrapeOptions / properties / max_scroll_steps / description

Added value: +"Cap scroll iterations when `scan_full_page` is true (1–200); omit for engine default."

addedInput schema / $defs / ScrapeOptions / properties / scan_full_page / description

Added value: +"Scroll the page to trigger lazy-loaded content; combine with `mode=full` or `max_scroll_steps`."

addedInput schema / $defs / ScrapeOptions / properties / user_agent / description
```
Added value: +"Override the default browser User-Agent for this render only."
```

addedInput schema / $defs / ScrapeOptions / properties / wait_for / description

Added value: +"CSS selector that must appear before capture; pairs with `wait_for_timeout_ms`."

addedInput schema / $defs / ScrapeOptions / properties / wait_for_timeout_ms / description
```
Added value: +"Max milliseconds to wait for `wait_for` (0–120000, default 10000)."
```

Changed7 schema fields changedNov 1, 2026

addedInput schema / properties / advanced / description

Added value: +"Browser interactions: scroll, wait_for selector, js_code, headers, cookies, locale, include_links, etc."

addedInput schema / properties / auth / description

Added value: +"Optional cookie, bearer, or basic auth for the page load."

addedInput schema / properties / format / description

Added value: +"Primary body field returned: markdown (default), plain text, or raw HTML."

addedInput schema / properties / fresh / description

Added value: +"When true, bypass cached scrape results (default false)."

addedInput schema / properties / mode / description

Added value: +"Whole-call budget and render depth: fast (15 s), render (30 s, default), or full (60 s with page scroll)."

addedInput schema / properties / url / description

Added value: +"Public http(s) URL to load in Chromium."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "billed": {
+      "type": "boolean"
+    },
+    "cache_status": {
+      "type": "string"
+    },
+    "markdown": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "status_code": {
+      "type": "integer"
+    },
+    "title": {
+      "type": "string"
+    },
+    "url": {
+      "format": "uri",
+      "type": "string"
+    }
+  },
+  "type": "object"
+}

First observedNov 1, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only say readOnlyHint=true and openWorldHint=true, so the description must carry the operational burden — and it does: one attempt with no retries, residential bandwidth as the cost driver, and a 4x price multiplier disclosed up front. Those are exactly the traits an agent needs to decide whether a call is worthwhile.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, each doing distinct work: mechanism, target class, cost/retry contract, and routing rule. The differentiator and the cost warning are front-loaded rather than buried.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With a full output schema present, the description needn't document return values, and annotations cover the read-only safety profile. The remaining gaps an agent would care about — price, retry behavior, egress type, and when to route here — are all stated.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is already 100%, so baseline is 3; the description earns an extra point by declaring the request shape identical to /v1/scrape, which lets the agent reuse known parameter semantics rather than re-deriving them. It adds no parameter-level detail of its own, so it stops short of a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource and mechanism — a render that egresses through a residential address instead of the datacentre — and explicitly ties it to '/v1/scrape' with identical request/response semantics. An agent can immediately distinguish it from readfetch_scrape without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It names the exact targets (DataDome, PerimeterX, Cloudflare, AWS WAF), gives an explicit preference ordering ('prefer readfetch_scrape when datacentre egress works'), and names a concrete trigger plus a diagnostic sibling ('only after readfetch_scrape fails or readfetch_probe reports a persistent challenge'). This is the full when/when-not/alternatives triad.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All ReadFetch tools Inspect

Try in Browser

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?