Fetch a page from a residential IP

When to use this

Pass a url; we request it as Chrome through a residential IP in country, without running JavaScript. For sites that refuse datacenter and ISP addresses, or serve each country its own page. 1–5 s. Always 5 credits, charged only when the page comes back; a call that's walled or can't reach the site fails with 502 upstream_error and costs nothing. For a page a site walls against this strategy, /v1/web/scrape (Auto) tries the others in turn, or /v1/web/custom chains the ones you pick. Pages over 2 MB are cut (truncated); use format=markdown for LLMs. The web scraping guide explains each strategy.

Parameters

All parameters go in the query string.

Example request

Replace YOUR_API_KEY with your key, or set LURKAPI_KEY for the code. Get a free key.

curl "https://api.lurkapi.com/v1/web/residential?url=https%3A%2F%2Fbooks.toscrape.com%2F&format=markdown" \
  -H "x-api-key: YOUR_API_KEY"

const params = new URLSearchParams({
  url: "https://books.toscrape.com/",
  format: "markdown",
});
const res = await fetch(`https://api.lurkapi.com/v1/web/residential?${params}`, {
  headers: { "x-api-key": process.env.LURKAPI_KEY },
});
const data = await res.json();
if (!data.success) throw new Error(`${data.code}: ${data.error}`);
console.log(data.content);

import os
import requests

res = requests.get(
    "https://api.lurkapi.com/v1/web/residential",
    params={
        "url": "https://books.toscrape.com/",
        "format": "markdown",
    },
    headers={"x-api-key": os.environ["LURKAPI_KEY"]},
    timeout=95,
)
data = res.json()
if not data["success"]:
    raise RuntimeError(f"{data['code']}: {data['error']}")
print(data["content"])

Example response

A real response from this endpoint, captured from the live API and trimmed to a couple of items. Strings over 96 characters (mostly signed media URLs) are cut short and end in ….

{
  "success": true,
  "credits_remaining": 9995,
  "credits_charged": 5,
  "status": 200,
  "url": "https://books.toscrape.com/",
  "content_type": "text/html",
  "content": "[Books to Scrape](https://books.toscrape.com/index.html) We love being s…",
  "truncated": false,
  "via": "residential",
  "captcha": null,
  "attempts": [
    {
      "via": "residential",
      "ms": 3085,
      "status": 200,
      "wall": null,
      "error": null
    }
  ],
  "billing": {
    "mode": "fixed",
    "credits": 5,
    "breakdown": {
      "base": 5
    },
    "note": null
  }
}

Response fields

Every field of a successful response. [] marks a list: a[].b is the b of each item in a. nullable fields can be null; optional fields can be missing.

Caching and freshness

Not cached: every call is answered fresh.

Errors

Errors return { success: false, error, code, docs } with the HTTP status below. Validation errors, 401/402/429 rejections and 5xx failures are free; not_found is charged (how charging works). All error codes.

Use it in Claude

Once LurkAPI is connected to Claude, this endpoint is the web_residential tool. Ask in plain English, for example:

Use LurkAPI's web_residential with url "https://books.toscrape.com/", format "markdown" and summarize what you find.

Claude calls web_residential with arguments like these, and each call costs 5 credits:

{
  "url": "https://books.toscrape.com/",
  "format": "markdown"
}

Tool results skip nulls and empty lists to save tokens.