API REFERENCE

Screenshot API documentation

Pass a URL and get back a screenshot or PDF, or extract structured data with AI. Reference for the /v1/screenshot and /v1/extract endpoints below — there's no SDK required.

Authentication

Every request needs your API key, either as a Bearer header or an api_key query parameter. Find your key on the dashboard.

curl

curl "https://snapurl.app/v1/screenshot?url=https://example.com" \
  -H "Authorization: Bearer sk_live_..." \
  -o shot.png

GET /v1/screenshot — capture a screenshot or PDF

Renders the page at url and streams back the image or PDF bytes directly.

Parameters

Param	Type	Default	Description
`url`	string, required	—	The page to capture. Must be a public, resolvable URL.
`format`	png / jpeg / webp / pdf	png	Output format.
`width`	int, 320–3840	1280	Viewport width in pixels.
`height`	int, 240–4320	800	Viewport height in pixels.
`full_page`	true / false	false	Capture the full scrollable page instead of just the viewport.
`wait_until`	load / domcontentloaded / networkidle	load	When to consider navigation finished.
`wait_for`	CSS selector	—	Wait for a selector to appear before capturing.
`delay`	int ms, 0–5000	—	Extra fixed delay before capture, on top of any wait conditions.
`selector`	CSS selector	—	Crop the capture to a single element instead of the whole viewport/page.
`block_ads`	true / false	true	Block common ad networks before rendering.
`block_cookie_banners`	true / false	true	Auto-dismiss common cookie consent banners.

GET /v1/extract — extract structured JSON

Renders the page at url and returns AI-extracted structured data as JSON. Available on the Starter and Growth plans — Free returns 403 plan_not_eligible.

Parameters

Param	Type	Default	Description
`url`	string, required	—	The page to extract from. Must be a public, resolvable URL.
`prompt`	string	—	Plain-language description of the data to extract. Required unless `schema` is given — exactly one of the two must be present.
`schema`	URL-encoded JSON object	—	A JSON schema-like object describing the fields to extract. Required unless `prompt` is given.
`include_screenshot`	true / false	false	Also render a 1280×800 screenshot and return it base64-encoded. Consumes one extraction and one screenshot render.

wait_until, wait_for, delay, block_ads, and block_cookie_banners behave exactly as documented above for /v1/screenshot.

Response

{ "data": { ... } }, with a base64 PNG screenshot field added when include_screenshot=true.

curl

curl "https://snapurl.app/v1/extract?url=https://example.com&prompt=Get+the+page+title" \
  -H "Authorization: Bearer $SNAPURL_KEY"

JavaScript

const res = await fetch(
  "https://snapurl.app/v1/extract?url=https://example.com&prompt=Get+the+page+title",
  { headers: { Authorization: `Bearer ${process.env.SNAPURL_KEY}` } }
)
const { data } = await res.json()

Python

import requests

res = requests.get(
    "https://snapurl.app/v1/extract",
    params={"url": "https://example.com", "prompt": "Get the page title"},
    headers={"Authorization": f"Bearer {SNAPURL_KEY}"},
)
data = res.json()["data"]

Errors

Errors come back as JSON with an error code, alongside the HTTP status.

Status	error	Meaning
400	`missing_url`	The `url` parameter was not provided.
400	`url_not_allowed`	The URL resolves to a private, local, or otherwise blocked address.
400	`bad_param`	A parameter failed validation. The offending param is included.
401	`invalid_api_key`	Missing, malformed, or revoked API key.
402	`quota_exceeded`	Free plans are capped at their monthly quota. Paid plans may burst past quota (billed as overage) up to a fixed multiple of it, after which requests are rejected until the next billing period.
402	`payment_suspended`	Your account is suspended pending payment.
403	`plan_not_eligible`	Your plan doesn't include this endpoint — e.g. `/v1/extract` on the Free plan.
408	`selector_timeout`	`wait_for` selector never appeared.
429	`rate_limited`	Too many requests per second for your plan. Includes a `retryAfter` in seconds.
502	`render_failed`	The page failed to render. Includes a `detail` message.

Rate limits & quotas

Plan	Screenshots / mo	Screenshot overage	Extractions / mo	Extraction overage
Free	25	not available — upgrade to continue	not included	not available — upgrade to continue
Starter	2,000	$5.00 / 1,000	200	$2.00 / 100
Growth	15,000	$3.00 / 1,000	2,000	$1.50 / 100

Identical requests are cached, and cache hits (x-cache: HIT) don't count against your quota. Paid plans can burst up to 3× their included quota per unit before being rejected with 402 quota_exceeded; overage past the included quota is billed monthly, and overage totaling under $0.50 in a month isn't invoiced.

Examples

curl

curl "https://snapurl.app/v1/screenshot?url=https://example.com&format=png&full_page=true" \
  -H "Authorization: Bearer $SNAPURL_KEY" \
  -o shot.png

JavaScript

const res = await fetch(
  "https://snapurl.app/v1/screenshot?url=https://example.com&format=png",
  { headers: { Authorization: `Bearer ${process.env.SNAPURL_KEY}` } }
)
const bytes = await res.arrayBuffer()

Python

import requests

res = requests.get(
    "https://snapurl.app/v1/screenshot",
    params={"url": "https://example.com", "format": "png"},
    headers={"Authorization": f"Bearer {SNAPURL_KEY}"},
)
open("shot.png", "wb").write(res.content)