REFETCH(1)                   Refetch Manual                   REFETCH(1)

NAME
  refetch.cloud — reliable web fetching for AI agents and automation

SYNOPSIS
  curl refetch.cloud/{url}
  curl refetch.cloud/md/{url}
  curl refetch.cloud/ld+json/{url}
  curl "refetch.cloud/s/news?q={query}"
  curl "refetch.cloud/s/web?q={query}"

DESCRIPTION
  Refetch retrieves publicly accessible web pages and returns them in
  machine-readable formats. Requests are routed through globally
  distributed infrastructure with automatic retries and intelligent
  block detection. Your IP address is never exposed to target sites.

  Each endpoint serves full documentation at its root path.

ENDPOINTS
  /{url}              Fetch page as raw HTML
  /md/{url}           Fetch page as clean Markdown
  /ld+json/{url}      Extract JSON-LD structured data
  /s/news?q=          Search news articles (structured JSON)
  /s/web?q=           Search the web (structured JSON)
  /usage              View your credit balance and usage history
  /limits             View rate limits and pricing
  /tos                Terms of Service
  /privacy            Privacy Policy

AUTHENTICATION
  All fetch and search endpoints require an API key.

  Headers:
    X-API-Key    (required)  Your API key (e.g. ftch_xxxxxxxx)

  Each request costs 1 credit. Documentation endpoints are free.

  Check your usage:  curl -H "X-API-Key: YOUR_KEY" refetch.cloud/usage
  Check limits:      curl refetch.cloud/limits

REQUEST
  URL Parameter:
    {url}              (required)  Full URL with scheme (https://example.com/page)

  Headers:
    X-Block-Patterns   (optional)  Comma-separated block detection patterns
                                   Example: X-Block-Patterns: captcha,paywall

  Query parameters are forwarded to the target URL.

RESPONSE
  200 OK
    Content-Type: forwarded from upstream (typically text/html)
    Body: raw HTML from the target page

  Response Headers (conditional):
    X-Resolved-URL     Set when a news redirect URL was auto-resolved

ERRORS
  All errors return Content-Type: application/json

    { "error": { "code": "ERROR_CODE", "message": "description" } }

  Code                       Status  Description
  ─────────────────────────────────────────────────────────────────────
  INVALID_URL                400     URL is malformed or missing scheme
  MISSING_PARAM              400     Required query parameter missing
  CONTENT_TYPE_NOT_ALLOWED   400     Upstream content type not supported
  RESPONSE_TOO_LARGE         400     Upstream response exceeds size limit
  RECURSIVE_PROXY            400     Cannot proxy requests to this service
  SEARCH_NOT_SUPPORTED       400     Search engine result pages not supported
  DOMAIN_RATE_LIMITED        429     Too many requests to target domain
  NO_LD_JSON                 404     No structured data found on page
  RATE_LIMITED               429     Upstream rate limit exceeded
  UPSTREAM_BLOCKED           502     Target site blocked the request
  NEWS_RESOLVE_FAILED        502     Could not resolve news redirect URL
  UPSTREAM_ERROR             502     Upstream fetch failed
  PROXY_SETUP_FAILED         503     Service temporarily unavailable
  PROXY_ERROR                503     Service temporarily unavailable
  INTERNAL_ERROR             500     Unexpected server error

SEE ALSO
  /md, /ld+json, /s/news, /s/web, /limits, /tos, /privacy

LEGAL
  By using this service you agree to the Terms of Service.

  Terms of Service:  refetch.cloud/tos
  Privacy Policy:    refetch.cloud/privacy