Fetch renders live pages and returns agent-ready Markdown, State JSON, evidence, and replayable snapshots.
Fetch renders live web pages and returns agent-ready Markdown, structured state, citations, and replayable snapshots. Start with the main content, then ask for more when the task needs it.
More answers, fewer tokens. Fetch separates signal from noise before your agent sees the page. It returns the main working document first, preserves structured state and spatial layout when they matter, and keeps deeper evidence reachable by reference instead of flooding the context window.
Less context does not mean throwing data away. Fetch preserves the page, then gives the agent the right entry point.
HTML-to-Markdown is not enough anymore. Fetch keeps the tables, icons, layout, hidden JSON, citations, and replay links that ordinary Markdown drops.
Send a URL, get back agent-ready context. The canonical call is POST /v1/fetch:
curl https://api.expand.ai/v1/fetch \
-H
Need a key and a first run? Start with the Quickstart.
Fetch gives agents the page as a working document, not a screenshot of the DOM and not a lossy scrape. One request returns layers an agent can read in order:
Frontmatter
Main Markdown
Spatial Markdown for tables, grids, icons, and layout
State JSON when useful
Appendix references
snapshotId
citations / Playground linkThe default is Markdown first, structured state when useful, and references to more when the agent needs depth.
Understand Main Markdown, State JSON, Appendix, snapshots, citations, and progressive disclosure.
See response fields, frontmatter, metadata, JSON Mode, snapshot IDs, and references.
Choose Markdown, State JSON, appendix, metadata, screenshots, HTML, response data, and more.
Understand JavaScript rendering, scrolling, screenshots, timeouts, and page limitations.
Ask focused questions over captured evidence without fetching the same page again.
Fetch turns one page into layers instead of one flattened stream. Each layer links to where it is defined in full.
| Layer | What it gives the agent | Go deeper |
|---|---|---|
| Frontmatter | Page metadata, URL, title, snapshot ID, and request context before the document body. | Output Model |
| Main Markdown | The high-signal working document your agent should read first. | How Fetch Works |
| Spatial Markdown |
Not every URL can be fetched. The domain may not resolve, the certificate may be broken, nothing may be listening, or the origin may answer with a 404. Those are the origin's failures, not Expand's, and Fetch reports them as such.
A non-2xx status means Expand failed. A 200 means Expand did its job, and the body reports what the origin did.
POST /v1/fetch/json returns a typed FetchOriginError instead of a document when the origin was never reached:
{
"_tag": "FetchOriginError",
"url": "https://checkout.deadstartup.example/pricing",
"kind": "dns",
"upstreamError": "net::ERR_NAME_NOT_RESOLVED",
"retryable": false
}When the origin did answer with an error status, the captured content still comes back — error pages are often the answer you needed — with the outcome attached beside it:
{
"meta": { "url": "https://site.example/removed-page", "title": "Page not found" },
"markdown": "# Page not found\n\n…",
"json": [],
"originError": {
POST /v1/fetch answers in Markdown, so the same facts ride the x-expand-origin-error, x-expand-origin-error-detail, and x-expand-origin-error-retryable response headers; when no document exists, the body is a short Markdown error document an agent can read directly.
kind is one of dns, tls, connectionRefused, connectionReset, connectionClosed, addressUnreachable, emptyResponse, connectionTimeout, or http. Trust retryable: it is derived from the exact Chromium network code, so transient resets, closes, empty responses, DNS timeouts, and connection timeouts report true. Unreachable origins are not billed; captured error pages are. See Error Handling for the full taxonomy and Pricing & Usage for billing by outcome.
The API, SDKs, CLI, MCP, and agents all call the same Fetch. Pick the one that fits your stack; the output model is the same.
| Path | Where to start |
|---|---|
| API | API Reference |
| TypeScript SDK | TypeScript SDK |
| Python SDK | Coming soon |
| CLI |
Use Fetch for agent research, docs ingestion, product and pricing pages, dashboard-like pages, JavaScript-rendered content, and any workflow where source evidence matters.
A simpler path may be enough for already-clean Markdown or a known API that exposes exactly the data you need. Browser automation is the better tool when the primary task is operating a site, filling forms, or completing a multi-step workflow.
Inspect what Fetch saw, debug citations, and share replayable evidence links.
| Layout-aware Markdown for tables, grids, icons, pricing pages, dashboards, and UI-heavy pages. |
| How Fetch Works |
| State JSON | Structured app and network state, included when it helps answer questions Markdown cannot. | How Fetch Works |
| Appendix | Secondary regions, navigation, sidebars, and links without flooding the main document. | Include Options |
| Evidence & Replay | Citations, source IDs, snapshotId, Playground links, and replayable captures. | Playground & Replay |
| MCP | MCP Tools & Resources |
| Agents | Agent Quickstarts |