ScrapeNest API

Returns metadata for the API key making the request. Use it to sanity-check auth and read your live rate limits.

curl https://scrapenest.dev/v1/me \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY"

import os, httpx

r = httpx.get(
    "https://scrapenest.dev/v1/me",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
)
r.raise_for_status()
print(r.json())

const r = await fetch("https://scrapenest.dev/v1/me", {
  headers: { "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}` },
});
console.log(await r.json());

Response

{
  "prefix": "sn_AbCdEfGhi",
  "label": "production",
  "is_active": true,
  "is_internal": false,
  "rate_limit_per_minute": 60,
  "rate_limit_per_day": 10000,
  "credit_balance": 48230,
  "created_at": "2026-05-01T12:00:00Z",
  "last_used_at": "2026-05-14T15:24:11Z"
}

Fetches a single URL and returns clean JSON. Use this when no dedicated endpoint exists for the source.

Request body

curl -X POST https://scrapenest.dev/v1/scrape/url \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "render": "auto",
    "extract": true
  }'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/scrape/url",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={
        "url": "https://example.com/article",
        "render": "auto",
        "extract": True,
    },
    timeout=60.0,
)
r.raise_for_status()
data = r.json()
print(data["title"], "-", data["credits_charged"], "credits")

const r = await fetch("https://scrapenest.dev/v1/scrape/url", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com/article",
    render: "auto",
    extract: true,
  }),
});
const data = await r.json();
console.log(data.title, "-", data.credits_charged, "credits");

Response

{
  "success": true,
  "url": "https://example.com/article",
  "final_url": "https://example.com/article",
  "status_code": 200,
  "method": "fetch",
  "proxy_used": "datacenter",
  "elapsed_ms": 312,
  "title": "Example Article",
  "description": "Lead summary...",
  "text": "Cleaned article body...",
  "structured": { "@type": "Article", "headline": "..." },
  "cache_hit": false,
  "escalated": false,
  "credits_charged": 1,
  "error": null,
  "error_code": null
}

Credit cost depends on the resolved tier: 1 direct, 5 browser-only, 10 residential-only, 40 residential+browser, 1 on a cache hit. Blocked and empty fetches are free.

Auto-escalation. When a non-stealth fetch is refused by the target’s anti-bot, we automatically retry once in stealth mode — you don’t need to resend anything. If that retry succeeds, escalated is true and credits_charged reflects the stealth rate; if it stays blocked, the request is free. Disable with auto_escalate: false.

When success is false, error_code is one of: anti_bot_block (anti-bot refused — already retried in stealth unless you disabled it), timeout (exceeded the time budget — raise timeout_seconds), not_found (target returned 404/410), empty_response (no usable content), or upstream_failed (transient fetch error — retry).

Fetches up to 10 URLs in a single call. Each URL is fetched independently and concurrently, so one URL failing never fails the rest. The render options apply to every URL in the batch.

Request body

curl -X POST https://scrapenest.dev/v1/scrape/batch \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/a",
      "https://example.com/b",
      "https://example.com/c"
    ],
    "render": "auto",
    "extract": true
  }'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/scrape/batch",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={
        "urls": [
            "https://example.com/a",
            "https://example.com/b",
            "https://example.com/c",
        ],
        "render": "auto",
        "extract": True,
    },
    timeout=120.0,
)
r.raise_for_status()
body = r.json()
print(body["succeeded"], "/", body["requested"], "-", body["credits_charged"], "credits")
for item in body["results"]:
    print(item["url"], item["ok"], item.get("title"))

const r = await fetch("https://scrapenest.dev/v1/scrape/batch", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    urls: [
      "https://example.com/a",
      "https://example.com/b",
      "https://example.com/c",
    ],
    render: "auto",
    extract: true,
  }),
});
const body = await r.json();
console.log(`${body.succeeded}/${body.requested} - ${body.credits_charged} credits`);
for (const item of body.results) console.log(item.url, item.ok, item.title);

Response (abbreviated)

{
  "results": [
    {
      "url": "https://example.com/a",
      "final_url": "https://example.com/a",
      "status_code": 200,
      "method": "fetch",
      "proxy_used": "datacenter",
      "elapsed_ms": 284,
      "title": "Page A",
      "text": "Cleaned body...",
      "structured": null,
      "ok": true,
      "credits_charged": 1,
      "error": null,
      "error_code": null
    },
    {
      "url": "https://example.com/blocked",
      "status_code": 403,
      "ok": false,
      "credits_charged": 0,
      "error": "anti-bot protection refused the request",
      "error_code": "anti_bot_block"
    }
  ],
  "requested": 3,
  "succeeded": 2,
  "credits_charged": 3
}

Each item carries its own ok, credits_charged, error, and error_code. error_code is a machine-readable failure category; anti_bot_block means the target’s anti-bot protection refused the request — retry that URL with render: "stealth". succeeded counts the items that returned a usable page; credits_charged at the top level is the sum across all items. When include_usage=true, the usage.breakdown reports the batch total under a single fetch key.

AI-friendly multi-engine web search. Returns the SERP (titles, URLs, snippets, engines, scores). No page fetching.

Request body

Leave engines unset to query the default mix — Google, Bing, and DuckDuckGo merged and deduped (when time_range is set the mix drops Bing, whose date filter can't be honoured; the response note reports the swap). An explicit engines list overrides the mix entirely. The "bing news" and "duckduckgo news" values pull straight from the news vertical — the same lane topic="news" routes to. depth matters mostly on /v1/search/deep, where it governs the per-page fetch budget and anti-bot effort; on plain /v1/search every depth queries the same engine mix, with thorough/stealth allowing extra time for the freshest engine data. page is 1-based offset pagination, so page=2 returns the next batch of results after the first.

curl -X POST https://scrapenest.dev/v1/search \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"climate report 2026 ipcc","num_results":10}'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/search",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"query": "climate report 2026 ipcc", "num_results": 10},
)
r.raise_for_status()
for item in r.json()["results"][:3]:
    print(item["position"], item["title"], "-", item["url"])

const r = await fetch("https://scrapenest.dev/v1/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "climate report 2026 ipcc", num_results: 10 }),
});
const body = await r.json();
for (const it of body.results.slice(0, 3)) {
  console.log(it.position, it.title, "-", it.url);
}

Response fields

Response (typical, abbreviated)

{
  "query": "climate report 2026 ipcc",
  "results": [
    {
      "position": 1,
      "url": "https://...",
      "title": "...",
      "snippet": "...",
      "engine": "google",
      "engines": ["bing", "duckduckgo", "google"],
      "score": 1.0,
      "published_at": "2026-04-12T14:30:00Z"
    }
  ],
  "took_ms": 318,
  "cache_hit": false,
  "credits_charged": 5
}

Response (when extras are populated; results omitted here for brevity)

{
  "query": "weather in tokyo",
  "results": [],
  "images": [
    {
      "url": "https://example.com/tokyo.jpg",
      "thumbnail": "https://example.com/tokyo_t.jpg",
      "title": "Tokyo skyline",
      "source_url": "https://example.com/article"
    }
  ],
  "suggestions": ["weather in tokyo tomorrow", "weather in tokyo this week"],
  "answers": [
    { "text": "Tokyo is currently 22°C, partly cloudy.", "source": "weather.com" }
  ],
  "infoboxes": [
    { "title": "Tokyo", "subtitle": "Capital of Japan", "url": "https://en.wikipedia.org/wiki/Tokyo" }
  ],
  "took_ms": 462,
  "cache_hit": false,
  "credits_charged": 5
}

Search and fetch the top N pages in one round trip. Same SERP as /v1/search, plus cleaned text for each fetched page.

Request body

All fields from /v1/search (including depth), plus:

Here depth also controls how hard we fetch each page. fast and balanced (default) fetch every page directly in parallel — lowest latency, and genuinely bot-walled pages simply fall back to their SERP snippet. thorough and stealth escalate bot-walled pages through a real-browser bypass with progressively larger per-page budgets; stealth has the best coverage on the hardest sites. Easy pages still return in a couple seconds regardless; the larger budget only applies to pages that actually need the bypass.

curl -X POST https://scrapenest.dev/v1/search/deep \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does retrieval-augmented generation work",
    "fetch_top": 3
  }'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/search/deep",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"query": "how does retrieval-augmented generation work", "fetch_top": 3},
    timeout=90.0,
)
body = r.json()
for page in body["pages"]:
    print(page["url"], "-", len((page.get("text") or "")), "chars")

const r = await fetch("https://scrapenest.dev/v1/search/deep", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "rag systems", fetch_top: 3 }),
});
const body = await r.json();
for (const p of body.pages) console.log(p.url, "-", (p.text || "").length);

Response (abbreviated; results carries the same SERP shape as /v1/search)

{
  "query": "how does retrieval-augmented generation work",
  "results": [],
  "pages": [
    {
      "url": "https://...",
      "final_url": "https://...",
      "status": 200,
      "method": "browser",
      "elapsed_ms": 640,
      "title": "...",
      "text": "..."
    }
  ],
  "took_ms": 2110,
  "fetched_count": 3,
  "cache_hit": false,
  "credits_charged": 20
}

RAG-style: searches the web, fetches the top sources, then asks an LLM to write a cited answer. Returns the answer plus [1]-style citations mapping to source URLs.

Request body

Accepts the same search fields as /v1/search (including depth) plus render ("auto" | "direct" | "browser", default "auto"). Instead of fetch_top, the number of sources to read is set by:

curl -X POST https://scrapenest.dev/v1/search/answer \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"is the new gpt-5 multimodal","max_sources":4}'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/search/answer",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"query": "is the new gpt-5 multimodal", "max_sources": 4},
    timeout=120.0,
)
body = r.json()
print(body["answer"])
for c in body["citations"]:
    print(f"[{c['index']}] {c['url']}")

const r = await fetch("https://scrapenest.dev/v1/search/answer", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "is gpt-5 multimodal", max_sources: 4 }),
});
const body = await r.json();
console.log(body.answer);
for (const c of body.citations) console.log(`[${c.index}] ${c.url}`);

Response (abbreviated)

{
  "query": "is the new gpt-5 multimodal",
  "answer": "Yes. GPT-5 supports text, image, audio... [1][2]",
  "citations": [
    { "index": 1, "url": "https://openai.com/...", "title": "...", "snippet": "..." }
  ],
  "took_ms": 4200,
  "cache_hit": false,
  "credits_charged": 30
}

Translate text between languages.

Request body

BCP-47 region aliases are normalised server-side: pt-BR, zh-Hant, zh-CN, en-GB, and underscore forms like en_US all map to the right target code. Pass whatever your stack hands you; no need to canonicalise.

curl -X POST https://scrapenest.dev/v1/translate \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world","target":"ja"}'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"text": "Hello world", "target": "ja"},
)
print(r.json()["translated"])

const r = await fetch("https://scrapenest.dev/v1/translate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Hello world", target: "ja" }),
});
console.log((await r.json()).translated);

Response

{
  "translated": "こんにちは世界",
  "detected_source": "en",
  "target": "ja",
  "credits_charged": 1
}

Response fields

• translated: the translated text.
• detected_source: the language we detected the source as (BCP-47).
• target: echoes the requested target language.
• note: only present when we adjusted behaviour (source equals target so text was returned unchanged, an alias was applied, or auto-detection fell back to a heuristic). Omitted from normal paid translations.
• credits_charged: 1 per call, or 0 when source equals (or auto-detects to) target.

Timestamped transcript of any audio source. Supports podcast episodes (Apple Podcasts, Overcast, RSS), YouTube (captions when available, else audio transcription), X Spaces, SoundCloud, Facebook video, TikTok, and direct MP3/M4A/WAV/OGG links.

Request body

curl -X POST https://scrapenest.dev/v1/audio/transcript \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://podcasts.apple.com/us/podcast/.../id..."}'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/audio/transcript",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"url": "https://podcasts.apple.com/us/podcast/.../id..."},
    timeout=600.0,
)
body = r.json()
print(body["title"], "/", body["channel"])
print(body["text"][:400])

const r = await fetch("https://scrapenest.dev/v1/audio/transcript", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://podcasts.apple.com/us/podcast/.../id..." }),
});
const body = await r.json();
console.log(body.title, "/", body.channel);
console.log(body.text.slice(0, 400));

Response (abbreviated)

{
  "url": "...",
  "audio_url": "https://traffic.megaphone.fm/....mp3",
  "canonical_url": "https://podcasts.apple.com/us/podcast/.../id...?i=...",
  "title": "Episode title",
  "channel": "Show name",
  "thumbnail": "https://is1-ssl.mzstatic.com/.../artwork.jpg",
  "duration_seconds": 3618.2,
  "language": "en",
  "source": "apple_podcasts",
  "chunks": [
    { "start": 0.0, "end": 4.2, "text": "Welcome back to the show..." }
  ],
  "text": "Welcome back to the show... [full transcript]",
  "took_ms": 41200,
  "cache_hit": false,
  "credits_charged": 620
}

chunks is omitted when the upstream source doesn’t provide timestamps (some podcast feeds and short clips); the text field always contains the full transcript regardless. canonical_url and thumbnail are populated when the resolver can pin them; treat absence as “not available”, not an error.

YouTube cookies (optional, for the long tail)

~95% of YouTube URLs work out of the box via the captions API. The remaining ~5% (YouTube Shorts that fall through the captions path, videos with auto-captions disabled, geo-restricted content, members-only, age-gated) require a logged-in YouTube session to download the audio. For those, pass a Netscape-format cookies.txt in the cookies field.

How to obtain cookies:

1. Use a burner Google account. Not your personal one, since every transcript request using these cookies adds to that account’s watch history.
2. Install a cookies-export browser extension (Chrome: Get cookies.txt LOCALLY; Firefox: cookies.txt).
3. Log into youtube.com in that browser, click the extension on any YouTube tab, choose Export. You’ll get a file starting with # Netscape HTTP Cookie File.
4. Send the entire file contents as the cookies field. We accept up to 128 KB; only the youtube.com lines actually matter.

Omit cookies for the typical case. Add it only when you’ve previously seen login_required on a video you specifically need.

Identical request shape to the sync endpoint. Returns immediately with a run_id (202 Accepted); poll GET /v1/scrape/runs/{run_id} for the completed transcript. Recommended for long-form audio (multi-hour podcasts, full conference talks) so you’re not holding an HTTP connection open for the duration of the transcription. Credit cost is identical and is charged when the job completes. Failed runs are not billed.

Initial response (202)

{
  "run_id": "f0e0c0a0-1234-5678-9abc-def012345678",
  "status": "queued",
  "status_url": "/v1/scrape/runs/f0e0c0a0-1234-5678-9abc-def012345678",
  "created_at": "2026-05-14T16:00:00Z",
  "expires_at": "2026-05-21T16:00:00Z"
}

Pulls Google Maps reviews for any place. Returns up to ~10,000 unique reviews, deduplicated and sorted newest-first.

Pricing. 100 credits per 50 reviews returned (rounded up to the next 50), with a 40-credit floor when 50 or fewer come back — so you only pay for what’s available. 200 reviews bills ~400 credits; the 10,000-review cap bills ~20,000.

Realistic delivery by place size

The note field in the response is your authoritative count of what came back and why. The review_count field reflects what Google publishes for the place, which is often much higher than what’s actually accessible through any documented endpoint. This reflects Google’s spam-filter and pagination behavior, not a limitation of this API.

Request body

Finding a FID

Open the place on Google Maps. The URL contains a segment like !1s0x47e6…:0x8ddc…!8m2!…. The FID is the 0x…:0x… hex pair immediately after !1s. Copy it whole, separator included.

curl -X POST https://scrapenest.dev/v1/scrape/google-maps/reviews \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "place_id": "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0",
    "max_reviews": 5000
  }'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/scrape/google-maps/reviews",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={
        "place_id": "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0",
        "max_reviews": 5000,
    },
    timeout=300.0,
)
body = r.json()
print(len(body["reviews"]), "reviews -", body["credits_charged"], "credits")

const r = await fetch("https://scrapenest.dev/v1/scrape/google-maps/reviews", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    place_id: "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0",
    max_reviews: 5000,
  }),
});
const body = await r.json();
console.log(body.reviews.length, "reviews -", body.credits_charged, "credits");

Response (abbreviated)

{
  "place_id": "0x47e66e2964e34e2d:0x8ddca9ee380ef7e0",
  "name": "London Eye",
  "address": "Riverside Building, County Hall, London SE1 7PB, UK",
  "rating": 4.5,
  "review_count": 89234,
  "google_maps_url": "https://www.google.com/maps/place/...",
  "reviews": [
    {
      "review_id": "ChdDSUhNMG9nS0VJQ0FnSURBNS0z...",
      "review_url": "https://www.google.com/maps/contrib/.../reviews?hl=en",
      "author_name": "Jane D.",
      "author_id": "1234567890",
      "author_profile_url": "https://www.google.com/maps/contrib/1234567890/reviews?hl=en",
      "author_avatar_url": "https://lh3.googleusercontent.com/...",
      "rating": 5,
      "text": "Amazing view, worth the wait.",
      "language": "en",
      "relative_time": "2 weeks ago",
      "posted_at": 1778630400,
      "posted_at_iso": "2026-05-13T00:00:00Z",
      "helpful_count": 4,
      "owner_reply": null
    }
  ],
  "star_histogram": [1820, 1140, 980, 1500, 4200],
  "note": "Returned 5000 unique reviews after deduplication.",
  "took_ms": 197000,
  "cache_hit": false,
  "credits_charged": 10000
}

Heads up: name, address, rating, review_count, and star_histogram can be null when the FID resolves but the metadata block isn’t served. The reviews array is always the source of truth for what you get.

star_histogram is a flat array of 5 ints ordered 1★ → 5★ (so [1820, 1140, 980, 1500, 4200] means 1820 one-star reviews, 4200 five-star reviews). photos is omitted from a review entry when the reviewer didn’t attach any; treat its absence as the empty case.

Identical request body to the sync endpoint. Returns immediately with a run_id (202 Accepted); poll GET /v1/scrape/runs/{run_id} for the final result. Recommended for any large pull (it doesn’t hold a long-lived HTTP connection open, and you can fire-and-forget across many places). Credit cost is identical and is charged when the job completes. Failed runs are not billed.

Initial response (202)

{
  "run_id": "f0e0c0a0-1234-5678-9abc-def012345678",
  "status": "queued",
  "status_url": "/v1/scrape/runs/f0e0c0a0-1234-5678-9abc-def012345678",
  "created_at": "2026-05-14T15:00:00Z",
  "expires_at": "2026-05-21T15:00:00Z"
}

Returns nearby retail gas-station prices for a US location. Accepts a 5-digit ZIP, City, ST, or City, State. Backed by public station-finder listings.

Request body

curl -X POST https://scrapenest.dev/v1/scrape/gas-prices \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "37122",
    "grade": "regular",
    "limit": 20
  }'

import os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/scrape/gas-prices",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"location": "Mount Juliet, TN", "grade": "regular", "limit": 20},
    timeout=60.0,
)
body = r.json()
for s in body["stations"][:5]:
    print(f"{s['brand']:>18}  {s.get('price')}  {s['address']}")

const r = await fetch("https://scrapenest.dev/v1/scrape/gas-prices", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ location: "37122", grade: "regular", limit: 20 }),
});
const body = await r.json();
for (const s of body.stations.slice(0, 5)) {
  console.log(`${s.brand}  ${s.price}  ${s.address}`);
}

Response (abbreviated)

{
  "location": {
    "query": "37122",
    "zip": "37122",
    "city": "Mount Juliet",
    "state": "TN"
  },
  "grade": "regular",
  "stations": [
    {
      "brand": "Kroger",
      "sub_brand": "Kroger Fuel Center",
      "station_id": "21847",
      "address": "401 S Mt Juliet Rd, Mount Juliet, TN",
      "city": "Mount Juliet",
      "state": "TN",
      "price": 2.789,
      "currency": "USD",
      "unit": "USD/gallon",
      "reporter": "anon_18234",
      "updated_relative": "12 minutes ago"
    }
  ],
  "region_stats": {
    "state": "TN",
    "region": "Tennessee",
    "region_type": "state",
    "lowest_price": 2.699,
    "average_price": 2.952
  },
  "source_url": "https://scrapenest.dev",
  "fetched_at": "2026-05-19T17:42:00Z",
  "took_ms": 1820,
  "cache_hit": false,
  "credits_charged": 10,
  "note": null
}

Field rules:

• location.zip, location.city, location.state are populated when the resolver can identify them; location.query always echoes the verbatim input.
• region_stats is omitted when the source doesn’t render the regional summary block (typically rural ZIPs).
• region_stats.region_type is "state" when region is a US state name and state holds the USPS code; it’s "city" when the source returned a metro-level summary (state is then null).
• note is set when stations were returned without per-station prices, when an ambiguous query was auto-resolved, or when other caveats apply.

Poll the status of any async run. Returns one of queued, running, completed, failed, cancelled. When completed, result holds the same body shape as the synchronous endpoint.

Polling does not consume credits, but it does count against your rate limit. Runs expire after 7 days.

The response also includes an optional progress object on long-running scrapes (currently large Maps reviews pulls). Shape: {"current": <int>, "target": <int>, "detail": "<string>"}. Use it to display a progress bar to your users; absent or null means the worker hasn't emitted a milestone yet.

To stop an in-flight run, hit POST /v1/scrape/runs/{run_id}/cancel. The worker stops on its next checkpoint (cooperative cancellation). No refund: cancellation is best-effort and any work already performed is billed.

RUN=$(curl -s -X POST https://scrapenest.dev/v1/scrape/google-maps/reviews/async \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"place_id":"0x47e6...:0x8ddc...","max_reviews":5000}' \
  | jq -r .run_id)

while true; do
  STATUS=$(curl -s https://scrapenest.dev/v1/scrape/runs/$RUN \
    -H "Authorization: Bearer $SCRAPENEST_API_KEY")
  STATE=$(echo "$STATUS" | jq -r .status)
  [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ] && { echo "$STATUS" | jq; break; }
  sleep 10
done

import os, time, httpx

API_KEY = os.environ["SCRAPENEST_API_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
BASE = "https://scrapenest.dev"

with httpx.Client(base_url=BASE, headers=HEADERS, timeout=30.0) as client:
    submit = client.post(
        "/v1/scrape/google-maps/reviews/async",
        json={"place_id": "0x47e6...:0x8ddc...", "max_reviews": 5000},
    )
    submit.raise_for_status()
    run_id = submit.json()["run_id"]

    while True:
        time.sleep(10)
        body = client.get(f"/v1/scrape/runs/{run_id}").json()
        if body["status"] in ("completed", "failed", "cancelled"):
            break

    if body["status"] == "completed":
        print(len(body["result"]["reviews"]), "reviews")
    else:
        print(body["status"], body.get("error_code"), body.get("error_message"))

const API_KEY = process.env.SCRAPENEST_API_KEY;
const BASE = "https://scrapenest.dev";
const headers = { "Authorization": `Bearer ${API_KEY}`, "Content-Type": "application/json" };

const submit = await fetch(`${BASE}/v1/scrape/google-maps/reviews/async`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    place_id: "0x47e6...:0x8ddc...",
    max_reviews: 5000,
  }),
});
const { run_id } = await submit.json();

while (true) {
  await new Promise(r => setTimeout(r, 10000));
  const body = await (await fetch(`${BASE}/v1/scrape/runs/${run_id}`, { headers })).json();
  if (["completed", "failed", "cancelled"].includes(body.status)) {
    console.log(body.status, body.result?.reviews?.length ?? body.error_message);
    break;
  }
}

Response (result holds the same body as the synchronous endpoint)

{
  "run_id": "f0e0c0a0-1234-5678-9abc-def012345678",
  "endpoint": "POST /v1/scrape/google-maps/reviews",
  "status": "completed",
  "created_at": "2026-05-14T15:00:00Z",
  "started_at": "2026-05-14T15:00:02Z",
  "completed_at": "2026-05-14T15:03:15Z",
  "cancelled_at": null,
  "expires_at": "2026-05-21T15:00:00Z",
  "credits_charged": 10000,
  "error_code": null,
  "error_message": null,
  "progress": null,
  "result": {}
}

Captures a PNG or JPEG screenshot of any public URL. Returns base64-encoded image bytes inline. Auto-falls-back to a stealth backend when the target site blocks the normal headless browser — same endpoint, same response shape. If you already know the target is hostile, skip the failed first attempt with render: "stealth".

Request body

curl -X POST https://scrapenest.dev/v1/scrape/screenshot \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://news.ycombinator.com",
    "full_page": true,
    "format": "png"
  }' \
  | jq -r .image_base64 | base64 -d > screenshot.png

import base64, os, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/scrape/screenshot",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={
        "url": "https://news.ycombinator.com",
        "full_page": True,
        "format": "png",
    },
    timeout=120.0,
)
r.raise_for_status()
data = r.json()
with open("screenshot.png", "wb") as f:
    f.write(base64.b64decode(data["image_base64"]))
print(f"{data['width']}x{data['height']}, {data['bytes']} bytes via {data['method']}")

import { writeFileSync } from "node:fs";

const r = await fetch("https://scrapenest.dev/v1/scrape/screenshot", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://news.ycombinator.com",
    full_page: true,
    format: "jpeg",
    jpeg_quality: 80,
  }),
});
const data = await r.json();
writeFileSync("screenshot.jpg", Buffer.from(data.image_base64, "base64"));
console.log(`${data.width}x${data.height}, ${data.bytes} bytes via ${data.method}`);

Response

{
  "url": "https://news.ycombinator.com",
  "final_url": "https://news.ycombinator.com/",
  "status_code": 200,
  "method": "browser",
  "proxy_used": null,
  "elapsed_ms": 2470,
  "width": 1280,
  "height": 1179,
  "bytes": 253264,
  "format": "png",
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "cache_hit": false,
  "credits_charged": 25
}

The method field tells you which engine handled the capture: "browser" is the normal headless path (~2–3 s, 15–25 credits), "stealth" is the anti-bot path for hostile sites (~8–12 s, 35 credits). You don't have to choose — we route per target — but render: "stealth" forces it when you already know the site blocks normal browsers.

Renders any URL to PDF. Returns base64-encoded bytes. Useful for archiving articles, generating invoice/receipt copies, or capturing legal evidence.

Request body

curl -X POST https://scrapenest.dev/v1/scrape/pdf \
  -H "Authorization: Bearer $SCRAPENEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/article",
    "format": "A4"
  }' | jq -r .pdf_base64 | base64 -d > article.pdf

import os, base64, httpx

r = httpx.post(
    "https://scrapenest.dev/v1/scrape/pdf",
    headers={"Authorization": f"Bearer {os.environ['SCRAPENEST_API_KEY']}"},
    json={"url": "https://example.com/article", "format": "A4"},
    timeout=120,
)
data = r.json()
with open("article.pdf", "wb") as f:
    f.write(base64.b64decode(data["pdf_base64"]))
print(f"{data['bytes']} bytes -> article.pdf")

import fs from "node:fs/promises";

const r = await fetch("https://scrapenest.dev/v1/scrape/pdf", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SCRAPENEST_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com/article", format: "A4" }),
});
const data = await r.json();
await fs.writeFile("article.pdf", Buffer.from(data.pdf_base64, "base64"));
console.log(`${data.bytes} bytes -> article.pdf`);

Response

{
  "url": "https://example.com/article",
  "final_url": "https://example.com/article",
  "status_code": 200,
  "proxy_used": null,
  "elapsed_ms": 2120,
  "format": "A4",
  "landscape": false,
  "bytes": 20925,
  "pdf_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago...",
  "cache_hit": false,
  "credits_charged": 25
}