Pass a URL. output: "markdown" keeps the structure, drops the markup and is far smaller than the HTML — the right choice when the page is going to a model.

bash

curl -X POST https://api.fetchlayer.dev/web-unblocker/fetch \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com/","output":"markdown"}'

The cheapest method that works is tried first

A plain direct read, then a browser, then a residential connection, then a residential connection with a verification step answered. Each rung costs more than the one before, and the response tells you which one actually served the page. A page that answers on the first rung never pays for the rest.

3. Read the usage block

This is the part worth knowing about. Every response carries usage, and it is there so you can audit a charge rather than trust it.

json

{
  "pagesFetched": 1,
  "usage": {
    "step": "plain-datacenter",
    "proxyTier": "datacenter",
    "exitCountry": null,
    "rendered": false,
    "captchaSolves": 0,
    "bytesTransferred": 34097,
    "requestsBlocked": 0,
    "totalMs": 598,
    "billableUnits": 1,
    "billing": "a direct fetch",
    "attempts": [
      {
        "step": "plain-datacenter",
        "outcome": "served",
        "status": 200,
        "proxyTier": "datacenter",
        "bytes": 34097,
        "durationMs": 577,
        "captchaSolves": 0,
        "reason": null
      }
    ]
  }
}

attempts lists every rung that was tried, in order, including the ones that failed and the ones that were skipped for lack of time — each with its status, bytes, duration and the reason it did not work. A request that cost more than you expected tells you exactly which rung it had to climb to and why the one below it did not work.

4. Cap how hard it tries

maxEffort is your ceiling: plain, render, residential, solve. It caps the top of the ladder rather than choosing a rung — the cheaper ones are always tried first regardless.

bash

curl -X POST https://api.fetchlayer.dev/web-unblocker/fetch \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com/","output":"markdown","maxEffort":"plain"}'

Use it when you would rather fail than pay

Sweeping ten thousand URLs where most are plain HTML? Cap at plain and re-run only the failures without the cap. The response says "Escalation was capped at \"plain\" as requested." in notes, so a capped failure is never mistaken for a broken page.

5. Do not accept a block page

A blocked request that answers 200 with a "please verify" page is the failure that quietly poisons a dataset. Name what must be there, and the request escalates instead of handing you the wrong content.

bash

curl -X POST https://api.fetchlayer.dev/web-unblocker/fetch \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","expectText":"Published","waitForSelector":"article h1"}'

6. Screenshot it instead

Same parameters, plus fullPage and imageFormat. The image comes back base64-encoded with its byte size and captured dimensions. A screenshot always needs a browser, so it starts at the rendered rung.

bash

curl -X POST https://api.fetchlayer.dev/web-unblocker/screenshot \
  -H "Authorization: Bearer ss-your-key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com/","fullPage":true,"imageFormat":"jpeg"}'

The one throughput ceiling

Answering an interactive captcha goes through a solving account capped at 2 concurrent across our whole fleet, shared with every other platform that uses it — roughly 4 to 12 solves per minute in total. It is not a per-key quota. A burst of pages that all need one will queue, and some will run out the 120-second budget and come back with the solve rung marked skipped. Cloudflare-style challenges use our own fleet and are not subject to it.

Errors and retries

A 400 names the field to fix, or says the address is one this service will not fetch. A 404 means the site has no page there, and the ladder stops rather than escalating at a page that does not exist. A 502 means the page answered in a way this service could not use. A 503 means every rung failed — it is not billed, and usage.attempts says what each rung tried and why it did not work.

Next steps

On this page