Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown
Browse docs

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown

Output Model

Understand the Markdown and JSON shapes returned by Fetch.

Fetch has two primary output views: a Markdown document for agents and a structured JSON Mode response for applications. Both carry the same capture, split differently: frontmatter/meta, Main Markdown, State JSON, Appendix references, snapshot handles, and evidence.

Markdown mode
POST /v1/fetch
-> text/markdown

JSON Mode
POST /v1/fetch/json
-> { meta, markdown, json, data }
curl https://api.expand.ai/v1/fetch \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com"}'

Next: See Include Options to control which fields come back, for exact schemas, or read for the capture model behind these fields.

Open API Reference
How Fetch Works

Markdown mode

POST /v1/fetch returns a Markdown document, not JSON. The document opens with YAML frontmatter and is followed by the Main Markdown body.

---
version: 1
url: https://example.com
capturedAt: 2026-06-24T...
snapshotId: ...
playground: https://expand.land/s/...
title: ...
stateJson:
  moreTokens: 1200
appendix:
  url: ...
  links:
    sameDomain: 42
    external: 7
---

# Main page title

Main Markdown body...
  • Frontmatter mirrors JSON Mode meta. Same values, expressed as YAML.
  • snapshotId is the stable handle for follow-up retrieval, Highlights, citations, and replay.
  • playground is the whole-capture inspection link, openable at https://expand.land/s/<snapshotId>.
  • stateJson, appendix, and markdown in frontmatter can be references or hints to more content rather than the content itself.
  • ?include= controls whether Markdown mode embeds State JSON and Appendix directly. The full request controls live in Include Options.

Frontmatter has more fields than shown here. See the API Reference for the exact schema instead of relying on this sketch.

JSON Mode

POST /v1/fetch/json returns the same capture as named fields an application can read directly.

{
  meta: {
    version: 1,
    url: string,
    capturedAt: string,
    snapshotId: string,
    playground: string,
    title?: string,
    finalUrl?: string,
    appendix?: { url: string, links: { sameDomain: number, external: number } },
    stateJson?: { moreTokens: number },
    markdown?: { url: string, moreTokens: number },
    blocked?: string,
    loadingStatus?: string
  },
  markdown: string,
  json: [
    {
      id: number,
      kind: "inline" |
  • meta is the frontmatter expressed as JSON.
  • markdown is the Main Markdown body without frontmatter or evidence sections.
  • json is State JSON evidence, one entry per preserved source.
  • Network State JSON includes a sanitized originating url and captured HTTP method when available.
  • urlRedacted: true means credentials were removed from the URL; urlOmitted explains why no URL was disclosed.
  • data.search holds Highlights results when you request them.
  • meta.appendix, meta.stateJson, and meta.markdown are references to more, not the content itself.

JSON Mode is not a different capture. It is the same Fetch output split into fields for applications.

State JSON is called json on the wire because it is data. In docs, State JSON means the selected page and network state Fetch preserved for reasoning.

Product terms vs field names

Product names map to specific wire fields and surfaces. This table resolves the naming, it does not add a new layer.

Product termField / surface
Main Markdownmarkdown
FrontmatterMarkdown YAML frontmatter / JSON Mode meta
State JSONjson, meta.stateJson, include=json, statejson in Markdown ?include=

References to more

When output would be too large or secondary to the main task, Fetch returns a reference instead of flooding the response.

You will see references in fields like:

  • meta.stateJson.moreTokens
  • meta.appendix.url
  • meta.markdown.url
  • json[].moreTokens
  • json[].keys
  • snapshotId
  • playground

References are not missing data. They are stable paths back to the capture when the task needs more depth. Follow them with Highlights or by opening the snapshot in Playground & Replay.

Citations and evidence fields

Evidence lives at the field level in Fetch output. Raw API Highlights snippets may include:

  • source
  • text
  • score
  • json
  • location

MCP and SDK helpers may add:

  • citationUrl

citationUrl is added by MCP tooling and SDK helpers. Raw API responses expose the location data needed to build citation links.

For snippet retrieval, see Highlights. For citation inspection and auditing, see Playground & Replay. For exact snippet schemas, see the API Reference.

Blocked and loading fields

A synchronous POST /v1/fetch can return a FetchBlocked error when a page cannot be captured. In JSON Mode, meta.blocked or meta.loadingStatus may appear on short-circuited or partial responses, and batched results can carry per-item blocked state.

These fields signal capture state only. For why a capture was blocked or partial, see Browser Behavior and the API Reference.

Next steps

  • Include Options: control which fields are returned.
  • Highlights: search captured evidence.
  • Playground & Replay: inspect snapshots and citations visually.
  • API Reference: see exact schemas.
PreviousHow Fetch Works
NextInclude Options

On This Page

Markdown modeJSON ModeProduct terms vs field namesReferences to moreCitations and evidence fieldsBlocked and loading fieldsNext steps
"network"
,
role: "ld+json" | "next-data" | "network-json" | "...",
score: number,
url?: string,
method?: string,
body?: unknown,
moreTokens?: number,
keys?: string[],
urlRedacted?: true,
urlOmitted?: "invalid" | "unsafe" | "too-long"
}
],
data?: {
search?: { query: string, snippets: [...] },
assets?: [...]
}
}
Appendixappendix, meta.appendix, include=appendix
Highlightsdata.search, /v1/fetch/search, fetch_search, expandai search
Evidence IDjson[].id, location.evidenceId, citation URLs
SnapshotsnapshotId, meta.playground