---
title: "Fetch JSON Mode"
method: POST
path: "/v1/fetch/json"
tags: ["Fetch"]
---

# Fetch JSON Mode

`POST /v1/fetch/json`

Fetch a URL and return a structured JSON response containing page metadata, Markdown, State JSON, and search results when requested.

## Query parameters

- `include` string — Include Options for the response. Use a comma-separated list with `appendix` for Appendix and `statejson` for State JSON. Defaults to State JSON when omitted; use `include=` for Markdown only. For search requests without a URL include parameter, the request body include fields define the search corpus.

## Request body

- object — Request parameters for fetching and extracting content from a web page
  - `url` string, required — The URL to fetch content from (http or https only)
  - `include` object — Specifies which content formats to include in the response
    - `html` union
      - boolean — Set to true to include HTML
      - object — Options for customizing HTML content extraction
    - `markdown` union
      - boolean — Set to true to include markdown
      - object — Options for customizing markdown content extraction
    - `screenshot` union
      - boolean — Set to true to include a screenshot
      - object — Options for customizing screenshot capture behavior
        - `fullPage` boolean — Whether to capture the full page including content below the fold
    - `links` union
      - boolean — Set to true to include links
      - object — Options for customizing link extraction
        - `sameDomainOnly` boolean — Only include links from the same domain as the fetched URL
        - `includePatterns` string[] — Regex patterns - only include links matching at least one pattern
        - `excludePatterns` string[] — Regex patterns - exclude links matching any pattern
    - `meta` boolean — Set to true to include page metadata
    - `response` object — Configure response info options (headers inclusion)
      - `includeHeaders` boolean — Whether to include HTTP response headers
    - `json` boolean — Include pruned JSON in the response (opt-in)
    - `appendix` boolean — Set to true to include extracted links and sidebar content
  - `search` object — Options for Highlights. When present, Fetch returns search results only.
    - `query` string, required — Query to find relevant snippets from the included Highlights corpus
    - `maxResults` integer — Maximum number of search snippets to return (1-50)
    - `minScore` number — Minimum relevance score threshold (0-1). Defaults to 0.6; set 0 to disable filtering.
  - `browserConfig` object — Configuration options for browser behavior during the fetch
    - `scrollFullPage` boolean — Whether to scroll the entire page to capture lazy-loaded content

## Response `200`

Fetch JSON Mode response for `/v1/fetch/json`. Mirrors the Markdown response as discrete fields for JSON-native consumers.

- FetchObjectModeResult — Fetch JSON Mode response for `/v1/fetch/json`. Mirrors the Markdown response as discrete fields for JSON-native consumers.
  - `meta` FetchObjectModeMeta, required — Structured page metadata in Fetch JSON Mode responses.
    - `version` 1, required — Schema version. Breaking shape changes bump this; additive fields do not.
    - `url` string, required
    - `capturedAt` string, required
    - `snapshotId` string, required
    - `lang` string, required
    - `pageType` string, required
    - `playground` string, required
    - `title` string
    - `finalUrl` string
    - `canonical` string
    - `description` string
    - `author` string
    - `createdAt` string
    - `updatedAt` string
    - `image` string
    - `paginationNext` string
    - `appendix` FetchObjectModeAppendixHint
      - `url` string, required — URL to fetch the full appendix. Lazy-loaded so default responses stay small.
      - `links` FetchObjectModeAppendixLinks, required — Appendix link counts grouped by destination.
        - `sameDomain` number, required — Number of appendix links on the captured domain.
        - `external` number, required — Number of appendix links pointing to other domains.
    - `stateJson` FetchObjectModeStateJsonHint
      - `moreTokens` number, required — Approximate token count available from the referenced state JSON evidence.
    - `markdown` FetchObjectModeMarkdownHint
      - `url` string, required — URL to fetch the full markdown for this snapshot.
      - `moreTokens` number — Approximate token count available from the referenced markdown. Not populated today: the hint names the route, and callers needing the size can ask it.
    - `blocked` string — HFC blocked sub-class when != none. Present only on short-circuited / partial responses.
    - `loadingStatus` string — HFC loading status when != none. Present only when the capture hit its deadline without settling.
  - `markdown` string, required — Main content body from the text/markdown response, without front-matter or evidence sections.
  - `json` FetchObjectModeEvidence[], required — Selected JSON evidence in canonical emission order.
    - `id` number, required — Evidence ID. Fetch via /s/<snapshotId>?id=<id>.
    - `kind` 'inline' | 'network', required
    - `role` 'ld+json' | 'next-data' | 'nuxt' | 'apollo-state' | 'initial-state' | 'application-json' | 'script-tag' | 'data-attribute' | 'network-json' | 'network-response' | 'other', required
    - `score` number, required — Evidence relevance score, 0–1.
    - `url` string — Sanitized originating request URL. Network only. See urlRedacted and urlOmitted for disclosure qualifiers.
    - `method` string — HTTP method. Network only.
    - `body` unknown
    - `moreTokens` number — Approximate token count omitted from referenced evidence.
    - `keys` string[] — Sample of top-level keys from referenced JSON evidence.
    - `urlRedacted` true — True when the sanitized URL differs from the captured URL because userinfo was removed or sensitive query values were replaced with REDACTED. Present only when redaction happened.
    - `urlOmitted` 'invalid' | 'unsafe' | 'too-long' — Reason the originating URL was withheld entirely: "invalid", "unsafe", or "too-long". Present only when url is absent.
  - `data` object — Additional fetch data for fields not represented in Markdown or selected JSON evidence.
    - `assets` FetchAssetReference[]
      - `id` string, required — Stable asset identifier. For data-url assets this is the decoded-byte SHA-256 hex digest.
      - `kind` 'data-url', required — Asset source kind.
      - `placeholder` string, required — Markdown/AST placeholder replacing the raw data URL.
      - `archiveKey` string, required — Synthetic WACZ archive key for retrieving the decoded asset bytes.
      - `mimeType` string, required — Decoded asset MIME type.
      - `sha256` string, required — Decoded-byte SHA-256 digest prefixed with sha256:.
      - `bytes` number, required — Decoded byte length.
    - `degraded` FetchDegradedInfo — Reduced-fidelity processing applied because the page crossed a configured processing threshold.
      - `reason` 'pageTooLarge' | 'modelInputTooLarge', required
      - `skipped` string[], required — Processing stages skipped; hfc is the HTML field-classification stage.
      - `limitKind` 'domsnapshot_bytes' | 'ast_bytes' | 'hfc_tokens', required
      - `measuredBytes` integer — Measured page size in bytes at the checkpoint that triggered degradation.
      - `thresholdBytes` integer — Configured degradation threshold in bytes.
      - `measuredTokens` integer — Tokenized HFC model input size in tokens.
      - `thresholdTokens` integer — Configured HFC input-token ceiling.
    - `search` FetchSearchResult
      - `query` string, required
      - `snippets` object[], required
        - `type` 'text' — Type identifier for TextPart compatibility
        - `source` 'markdown' | 'appendix' | 'statejson', required
        - `text` string, required — Readable snippet content
        - `json` unknown
        - `score` number, required — Normalized fused relevance score (0-1)
        - `location` FetchSearchSnippetLocation
          - `evidenceId` integer — an integer
          - `markdownBlockId` string — Deprecated Source Block identity; use evidenceId
          - `nodeIds` number[] — Deprecated replay element linkage; use evidenceId for public citations
          - `stateJsonSourceId` number — Deprecated State JSON source-object index; use evidenceId for public citations
          - `jsonPath` string — JSON path for State JSON snippets
      - `meta` FetchSearchMeta
        - `durationMs` number, required — Total elapsed search time in milliseconds.
        - `sources` FetchSearchSourceMeta[], required
          - `source` 'markdown' | 'appendix' | 'statejson', required
          - `chunkCount` integer, required — Number of search chunks considered for this source.
          - `batchCount` integer, required — Number of ranking batches evaluated for this source.
          - `ranker` 'zeroentropy' | 'mixedbread' | 'local_lexical', required
          - `fallback` boolean, required
          - `fallbackReason` 'timeout' | 'error'
          - `durationMs` number, required — Elapsed search time for this source in milliseconds.
    - `screenshot` object — Screenshot of the fetched page
      - `url` string, required — Presigned URL for the screenshot image
      - `fullPage` boolean, required — Whether the screenshot captures the full scrollable page or just the viewport

## Other responses

- `400` — The request did not match the expected schema
- `401` — AuthFailed
- `403` — AccessBlocked
- `413` — PayloadTooLarge
- `429` — TooManyRequests
- `500` — InternalError
- `502` — FetchNavigationFailed
- `503` — ServiceUnavailable
- `504` — FetchCaptureTimeout
- `529` — FetchCapacityTimeout

---

[API](https://skmtc.dev/expand/apis/expand-ai-api.md) · [All operations](https://skmtc.dev/expand/apis/expand-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/expand/expand-ai-api/revisions/dd6849b4a636/schema)