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

Highlights

Search a Fetch capture for ranked, cited snippets from Markdown, State JSON, and Appendix.

Highlights finds the most relevant passages inside a Fetch capture, so your agent can answer focused questions without re-fetching the page or loading the whole document into context.

It searches the evidence Fetch already captured and returns the best snippets from Main Markdown, State JSON, and optionally Appendix, each with a relevance score and a source location you can cite.

The mental model:

snapshotId + query
-> ranked snippets
-> source: markdown | appendix | statejson
-> citation / Playground link

Highlights is the product name. The API, CLI, and MCP surfaces still use technical names such as /v1/fetch/search, expandai search, and fetch_search.

Jump to: Choose Corpus · Inspect Citations · Open API Reference

Two ways to call Highlights

Search while fetching, or search a snapshot you already captured.

# Search a snapshot you already have (no re-capture)
expandai search <snapshotId> "AI agent browser"
# Search while fetching, in one request
curl https://api.expand.ai/v1/fetch/json \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "search": { "query": "AI agent browser", "maxResults": 3 },
    "include": { "markdown": true, "json": true }
  }'

A response carries ranked snippets, not the whole page:

{
  "search": {
    "query": "AI agent browser",
    "snippets": [
      {
        "source": "markdown",
        "text": "Show HN: peerd - AI agent harness that runs entirely in your browser...",
        "score

What Highlights does

Highlights searches the evidence Fetch already captured. It returns the best snippets from Main Markdown, State JSON, and optionally Appendix, instead of returning the whole page again.

This is how an agent can answer more questions with fewer tokens: read the main document first, then use Highlights when the task needs a focused passage or structured evidence.

Reach for it to:

  • ask a targeted question about a long captured page;
  • retrieve exact evidence for an answer;
  • search State JSON without dumping all of it into context;
  • reuse a snapshot instead of fetching the same URL again;
  • return citations to a user.
Fetch once -> snapshotId -> Highlights queries without re-capture

Search while fetching

Inline Highlights starts a new Fetch capture and returns matching snippets from the included corpus. Add a search object to a /v1/fetch or /v1/fetch/json request. JSON Mode shows the response shape most clearly.

curl https://api.expand.ai/v1/fetch/json \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "search": {
      "query": "AI agent browser",
      "maxResults": 3,
      "minScore": 0
    },
    "include": {
      "markdown": true,
      "json": true
    }
  }'

In search mode, JSON Mode returns snippets under data.search and suppresses the ordinary payloads (full Markdown, State JSON, HTML, screenshots, links, Appendix):

{
  "meta": {
    "version": 1,
    "url": "https://news.ycombinator.com/",
    "capturedAt": "2026-06-24T17:44:50.852Z",
    "snapshotId": "019...",
    "lang":

In search mode, markdown and json are not the full page output. They may be empty while data.search.snippets carries the focused results.

Search an existing Fetch

Snapshot Highlights searches a previous Fetch by snapshotId. It does not start a new browser capture. The CLI is the shortest path for humans and agents:

expandai search <snapshotId> "AI agent browser"

The same call over the raw API hits POST /v1/fetch/search:

curl https://api.expand.ai/v1/fetch/search \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshotId": "019...",
    "search": {
      "query": "AI agent browser",
      "maxResults": 2,
      "minScore": 0
    },
    "include": {
      "markdown": true,
      "json": true,
      "appendix": false
    }
  }'

The snapshot search response wraps the snippets with the source response and timing:

{
  "snapshotId": "019...",
  "response": {
    "url": "https://news.ycombinator.com/",
    "originStatusCode": 200
  },
  "search": {
    "query": "AI agent browser"

Batched Fetch does not support Highlights. Search a single snapshot, or run inline Highlights on a single /v1/fetch request.

Markdown and State JSON together

One Highlights response can mix readable Markdown evidence and structured State JSON evidence. Here, a query for plan limit matches a table row in Markdown and the underlying frontend value in State JSON:

{
  "search": {
    "query": "plan limit",
    "snippets": [
      {
        "source": "markdown",
        "text": "| Pro | 10 projects | 50 seats |",
        "score"

Markdown snippets are readable evidence. State JSON snippets can carry the structured value that produced the match. Agents should use both: quote the readable text when it answers the question, and use State JSON when the page's frontend data contains the precise value.

State JSON snippets are not guaranteed. They appear when State JSON is included and relevant structured state exists.

Markdown snippet       State JSON snippet
readable sentence      structured value
evidenceId             evidenceId + jsonPath

Corpus selection

For Highlights, include options choose the search corpus. They are not just output toggles.

  • include.markdown searches Main Markdown.
  • include.json searches State JSON.
  • include.appendix searches Appendix when Appendix text exists.
  • Inline Highlights with no include defaults to Markdown plus State JSON.
  • Snapshot Highlights with no include defaults to Markdown plus State JSON.
  • Appendix is opt-in.
  • A request with no searchable corpus is rejected.
Main Markdown
State JSON
Appendix
    |
    v
Highlights
    |
    v
ranked snippets + source locations

Turning every corpus off leaves nothing to search:

{
  "search": { "query": "pricing" },
  "include": {
    "markdown": false,
    "json": false,
    "appendix": false

This request has no corpus to search, so it should fail before ranking. See Include Options for the full field matrix.

Snippet fields

FieldMeaning
queryThe query that was searched.
snippets[]Ranked snippet results.
sourcemarkdown, appendix, or statejson.

Citations and Playground links

Raw API snippets expose location. CLI text output prints an auditable citation link in each snippet header. MCP adds citationUrl fields so agents can return Playground links directly.

CLI text output:

[markdown · score 1.00] https://expand.land/s/019...?id=858

Show HN: peerd - AI agent harness that runs entirely in your browser...

MCP-enriched snippet:

{
  "source": "statejson",
  "text": "planLimits.pro.projects: 10",
  "json": { "projects": 10 },
  "score": 0.91,
  "citationUrl": "https://expand.land/s/019...?id=3"
}

citationUrl is not a raw API field. MCP adds it from the snippet's evidence id, and the CLI adds it to both text and JSON output.

You do not need that field to cite. Expand stamps an evidence id into the captured Markdown next to the text it belongs to, written as {1199}, and every result carries a playground URL for the snapshot. Any citation is those two joined:

<playground>?id=<evidence id>

That rule works for anything you read, not just search snippets — which is why the markers are inline in the Markdown.

To inspect a citation visually, open the snapshot in Playground & Replay.

Defaults and tuning

SurfaceKnobDefault
APImaxResults5
API / CLIminScore0.6
CLI--max-results

The CLI supports --format text and --format json, plus --min-score and --max-results. MCP fetch_search exposes includeMarkdown, includeAppendix, and includeJson.

expandai search <snapshotId> "pricing limits" --max-results 10 --min-score 0.5

The same knobs over the raw API:

{
  "snapshotId": "019...",
  "search": {
    "query": "pricing limits",
    "maxResults": 10,
    "minScore": 0.5
  }
}

Empty results and errors

Tell these apart:

  • Zero snippets means the corpus was valid but nothing met the score threshold. Lower minScore or widen the corpus.
  • Empty corpus means the request is invalid. The current error wording is Fetch Search requires at least one included corpus: markdown, json, or appendix.
  • Missing or inaccessible snapshotId is a snapshot lookup or ownership error, not a ranking outcome.
  • Blocked fetches are Fetch errors, not Highlights ranking errors.

Ranking is not deterministic for every query. It can change as the capture, corpus, and ranker improve, so do not depend on a fixed snippet order or on debug-only ranking metadata.

Technical name mapping

Use Highlights in prose. Use the technical names only when showing API routes, CLI commands, MCP tools, or field names.

Product termTechnical surface
HighlightsProduct capability
Inline Highlightssearch on /v1/fetch or /v1/fetch/json
Snapshot HighlightsPOST /v1/fetch/search
JSON Mode field

Next steps

  • Include Options: choose the search corpus.
  • Playground & Replay: inspect citations visually.
  • Output Model: understand snapshotId, State JSON, and evidence fields.
  • API Reference: see exact endpoint schemas and response examples.
PreviousBrowser Behavior
NextPlayground & Replay

On This Page

Two ways to call HighlightsWhat Highlights doesSearch while fetchingSearch an existing FetchMarkdown and State JSON togetherCorpus selectionSnippet fieldsCitations and Playground linksDefaults and tuningEmpty results and errorsTechnical name mappingNext steps
"
: 1,
"location": { "evidenceId": 858 }
}
]
}
}
"en"
,
"pageType": "article",
"playground": "https://expand.land/s/019..."
},
"markdown": "",
"json": [],
"data": {
"search": {
"query": "AI agent browser",
"snippets": [
{
"type": "text",
"source": "markdown",
"text": "Show HN: peerd - AI agent harness that runs entirely in your browser...",
"score": 1,
"location": { "evidenceId": 858 }
}
]
}
}
}
,
"snippets": [
{
"source": "markdown",
"text": "Show HN: peerd - AI agent harness that runs entirely in your browser...",
"score": 1,
"location": { "evidenceId": 858 }
}
]
},
"durationMs": 107
}
: 0.94,
"location": { "evidenceId": 1204 }
},
{
"source": "statejson",
"text": "planLimits.pro.projects: 10",
"json": {
"plan": "pro",
"projects": 10,
"seats": 50
},
"score": 0.91,
"location": {
"evidenceId": 3,
"jsonPath": "$.planLimits.pro"
}
}
]
}
}
}
}
text
Readable snippet content.
jsonStructured State JSON value when the source is statejson and the value fits inline.
scoreNormalized relevance score from 0 to 1.
location.evidenceIdCanonical public Evidence ID for the snippet when available.
location.jsonPathJSON path for State JSON snippets when available.
5
CLI--min-score0.6
MCP fetch_searchnested minScore0
data.search
MCP toolfetch_search
CLI commandexpandai search
Citation linkPrinted by CLI text output; citationUrl field in MCP-enriched results