API reference — FetchRelay

Your first API request

Create an API key in Account. Store it in a server environment variable named FETCHRELAY_API_KEY.
Run this command in your terminal. It requests one public page.
Check that success is true and data.markdown contains the page text. Review the metadata and warnings before using the result.

curl --fail-with-body --max-time 300 'https://fetchrelay.com/api/scrape' \
  -H "Authorization: Bearer ${FETCHRELAY_API_KEY:?Set FETCHRELAY_API_KEY first}" \
  -H "Content-Type: application/json" \
  --data-raw '{
  "url": "https://example.com",
  "formats": [
    "markdown"
  ]
}'

Authentication uses Authorization: Bearer YOUR_KEY. Limited anonymous trials are available for synchronous extraction; saved jobs, monitors, and MCP require an account. Never expose your key in frontend code. All request bodies use JSON.

Background jobs and retries

Send async: true to crawl or batch. A 202 response returns a job ID and statusUrl.
GET that status URL with the same API key, a few seconds apart. Stop when data.status is completed, partial, failed, or cancelled.
Download /api/crawl/{id}/results?format=jsonl, or choose JSON or CSV. For large datasets, use offset and limit and check X-Total-Count.

Do not repeat the start request to poll: another POST can start and charge for another job. After a client timeout, inspect saved runs before starting again. Partial results remain useful even when some pages fail. Successful pages cost one credit each; unused reserved credits are released.

Handle unsuccessful responses

400 / 415: fix the request fields or JSON content type.
401 / 403: check authentication and permissions; read the error message for source-site restrictions.
402 / 429: check credits or rate limits. Wait before retrying; do not loop immediately.
5xx: a request or provider could not complete. Keep the response’s X-Request-Id for support.

Search and managed proxy/browser options require separately configured providers. Their presence in the API schema does not mean they are enabled. Browser rendering does not guarantee access through login walls or bot challenges.

POST /api/scrape

Scrape one URL

url string · required

See the OpenAPI schema for nested fields.

formats array of string · optional

Product resolves a primary entity from JSON-LD or scoped microdata, then uses Open Graph or labelled product attributes when available. Ambiguous or missing products return null in mixed-format responses; product-only requests fail with 502. Unconfirmed prices are omitted. Inspect diagnostics.warnings; a fetched page is not a guarantee of complete product fields. Values: markdown, html, rawHtml, text, links, images, screenshot, product, branding.

mode string · optional

One of: auto, http, browser. Default: "auto".

browserProvider string · optional

Managed browser requires a configured provider. One of: local, managed.

proxy string · optional

Residential requires an eligible managed-browser plan. One of: none, residential.

onlyMainContent boolean · optional

Default: true.

waitFor integer · optional

Minimum: 0. Maximum: 10000.

timeout integer · optional

Minimum: 3000. Maximum: 55000.

maxAge integer · optional

Minimum: 0. Maximum: 86400000.

mobile boolean · optional

See the OpenAPI schema for nested fields.

redactPII boolean · optional

See the OpenAPI schema for nested fields.

previousHash string · optional

See the OpenAPI schema for nested fields.

headers object · optional

See the OpenAPI schema for nested fields.

extract object · optional

Caller-provided CSS fields, returned in data.extract. Numeric fields use the document language for decimal/group separators and return null when the value is ambiguous. Use text to preserve the original representation. Selectors are specific to the target layout.

actions array of object · optional

Up to 20 items.

Responses

200 — Extracted document

POST /api/batch

Scrape 20 URLs synchronously or 1000 asynchronously

formats array of string · optional

Product resolves a primary entity from JSON-LD or scoped microdata, then uses Open Graph or labelled product attributes when available. Ambiguous or missing products return null in mixed-format responses; product-only requests fail with 502. Unconfirmed prices are omitted. Inspect diagnostics.warnings; a fetched page is not a guarantee of complete product fields. Values: markdown, html, rawHtml, text, links, images, screenshot, product, branding.

mode string · optional

One of: auto, http, browser. Default: "auto".

browserProvider string · optional

Managed browser requires a configured provider. One of: local, managed.

proxy string · optional

Residential requires an eligible managed-browser plan. One of: none, residential.

onlyMainContent boolean · optional

Default: true.

waitFor integer · optional

Minimum: 0. Maximum: 10000.

timeout integer · optional

Minimum: 3000. Maximum: 55000.

maxAge integer · optional

Minimum: 0. Maximum: 86400000.

mobile boolean · optional

See the OpenAPI schema for nested fields.

redactPII boolean · optional

See the OpenAPI schema for nested fields.

previousHash string · optional

See the OpenAPI schema for nested fields.

headers object · optional

See the OpenAPI schema for nested fields.

extract object · optional

Caller-provided CSS fields, returned in data.extract. Numeric fields use the document language for decimal/group separators and return null when the value is ambiguous. Use text to preserve the original representation. Selectors are specific to the target layout.

actions array of object · optional

Up to 20 items.

urls array of string · required

Up to 1000 items.

async boolean · optional

Default: false.

Responses

200 — Batch result

202 — Saved batch job; follow statusUrl

POST /api/crawl

Crawl a website synchronously or asynchronously

url string · required

See the OpenAPI schema for nested fields.

formats array of string · optional

Product resolves a primary entity from JSON-LD or scoped microdata, then uses Open Graph or labelled product attributes when available. Ambiguous or missing products return null in mixed-format responses; product-only requests fail with 502. Unconfirmed prices are omitted. Inspect diagnostics.warnings; a fetched page is not a guarantee of complete product fields. Values: markdown, html, rawHtml, text, links, images, screenshot, product, branding.

mode string · optional

One of: auto, http, browser. Default: "auto".

browserProvider string · optional

Managed browser requires a configured provider. One of: local, managed.

proxy string · optional

Residential requires an eligible managed-browser plan. One of: none, residential.

onlyMainContent boolean · optional

Default: true.

waitFor integer · optional

Minimum: 0. Maximum: 10000.

timeout integer · optional

Minimum: 3000. Maximum: 55000.

maxAge integer · optional

Minimum: 0. Maximum: 86400000.

mobile boolean · optional

See the OpenAPI schema for nested fields.

redactPII boolean · optional

See the OpenAPI schema for nested fields.

previousHash string · optional

See the OpenAPI schema for nested fields.

headers object · optional

See the OpenAPI schema for nested fields.

extract object · optional

Caller-provided CSS fields, returned in data.extract. Numeric fields use the document language for decimal/group separators and return null when the value is ambiguous. Use text to preserve the original representation. Selectors are specific to the target layout.

actions array of object · optional

Up to 20 items.

async boolean · optional

Default: false.

limit integer · optional

Synchronous maximum 100; asynchronous maximum 1000. Minimum: 1. Maximum: 1000.

maxDepth integer · optional

Minimum: 0. Maximum: 10.

sitemap string · optional

One of: include, skip, only.

includePaths array of string · optional

See the OpenAPI schema for nested fields.

excludePaths array of string · optional

See the OpenAPI schema for nested fields.

allowSubdomains boolean · optional

See the OpenAPI schema for nested fields.

allowExternalLinks boolean · optional

See the OpenAPI schema for nested fields.

webhook string · optional

See the OpenAPI schema for nested fields.

Responses

200 — Synchronous result

202 — Queued crawl job

GET /api/crawl/{id}

Get crawl status

Responses

200 — Crawl job

DELETE /api/crawl/{id}

Cancel a crawl

Responses

200 — Cancelled job

GET /api/crawl/{id}/results

Download partial or completed crawl results

format · query · One of: json, jsonl, csv. Default: "json".

offset · query · Default: 0. Minimum: 0.

limit · query · Default: 100. Minimum: 1. Maximum: 1000.

Responses

200 — Dataset download; X-Total-Count and X-Crawl-Status describe progress.

POST /api/mcp

MCP Streamable HTTP endpoint

Responses

200 — MCP JSON-RPC response

202 — Notification accepted

POST /api/search

Search the web and optionally extract results

query string · required

See the OpenAPI schema for nested fields.

limit integer · optional

Default: 5. Minimum: 1. Maximum: 10.

scrape boolean · optional

Default: false.

includeDomains array of string · optional

Up to 10 items.

excludeDomains array of string · optional

Up to 10 items.

scrapeOptions object · optional

See the OpenAPI schema for nested fields.

Responses

200 — Ranked results and optional per-URL extraction

503 — Search provider not configured

GET /api/monitors

List your saved monitors

Responses

200 — Monitor list

POST /api/monitors

Create a scheduled page monitor

url string · required

See the OpenAPI schema for nested fields.

formats array of string · optional

Product resolves a primary entity from JSON-LD or scoped microdata, then uses Open Graph or labelled product attributes when available. Ambiguous or missing products return null in mixed-format responses; product-only requests fail with 502. Unconfirmed prices are omitted. Inspect diagnostics.warnings; a fetched page is not a guarantee of complete product fields. Values: markdown, html, rawHtml, text, links, images, screenshot, product, branding.

mode string · optional

One of: auto, http, browser. Default: "auto".

browserProvider string · optional

Managed browser requires a configured provider. One of: local, managed.

proxy string · optional

Residential requires an eligible managed-browser plan. One of: none, residential.

onlyMainContent boolean · optional

Default: true.

waitFor integer · optional

Minimum: 0. Maximum: 10000.

timeout integer · optional

Minimum: 3000. Maximum: 55000.

maxAge integer · optional

Minimum: 0. Maximum: 86400000.

mobile boolean · optional

See the OpenAPI schema for nested fields.

redactPII boolean · optional

See the OpenAPI schema for nested fields.

previousHash string · optional

See the OpenAPI schema for nested fields.

headers object · optional

See the OpenAPI schema for nested fields.

extract object · optional

Caller-provided CSS fields, returned in data.extract. Numeric fields use the document language for decimal/group separators and return null when the value is ambiguous. Use text to preserve the original representation. Selectors are specific to the target layout.

actions array of object · optional

Up to 20 items.

name string · required

See the OpenAPI schema for nested fields.

intervalMinutes integer · optional

Default: 1440. Minimum: 60. Maximum: 10080.

webhook string · optional

See the OpenAPI schema for nested fields.

Responses

201 — Created; first baseline queued

GET /api/monitors/{id}

Get your monitor and last 30 checks

Responses

200 — Monitor, history and diffs

PATCH /api/monitors/{id}

Pause/resume, or request a check

enabled boolean · optional

See the OpenAPI schema for nested fields.

action string · optional

One of: run.

Responses

200 — Updated monitor

DELETE /api/monitors/{id}

Delete your monitor and history

Responses

200 — Deleted

POST /api/map

Discover URLs from sitemaps and page links

Responses

200 — URL map