One endpoint turns a URL or your own HTML into a PNG, JPEG, WebP or PDF. Cookie banners, popups, chat widgets, ads and trackers are handled by default, and only clean, freshly rendered shots count toward your plan. The machine-readable version of this page is openapi.json.
Add full_page=true for the whole page, device=iphone_15 for a phone, format=pdf for a PDF, or response_type=json for a file URL plus the page’s title, description and Open Graph data.
Authentication
Send your key as access_key in the query or JSON body, as an X-Access-Key header, or as Authorization: Bearer YOUR_KEY. Keys are shown once and stored only as a hash; revoke and replace them from the dashboard. Each key also has a signing secret for signed links and webhook signatures.
Endpoints
Method and path
What it does
GET /v1/shot
Capture a URL; parameters in the query string.
POST /v1/shot
The same with a JSON (or form) body, needed for html, and handy for headers, cookies and scripts.
GET /v1/jobs/{id}
State and result of an async job.
POST /v1/bulk
Queue up to 100 captures at once.
GET /v1/bulk/{id}
Progress of a batch, with every job’s result.
GET /v1/usage
Plan, quota, use and reset date for the key’s account.
GET /v1/files/{name}
A stored result from a JSON or async response (no key needed; the name can’t be guessed).
POST /mcp
MCP server for AI agents (Streamable HTTP).
Input
Parameter
Values
What it does
url
string
The page to capture. https:// is added when missing. Private and internal addresses are refused, including through redirects.
html
string
Raw HTML to render instead of a URL (POST it in a JSON body). Good for Open Graph images and templates. Up to 2 MB.
Output
Parameter
Values
What it does
format
png · jpeg · webp · pdfdefault png
Output format. jpg is accepted for jpeg.
qualityalso image_quality
1–100default 80
JPEG and WebP quality.
image_widthalso thumb_width, thumbnail_width
16–3840
Resize the result to this width (thumbnails). With image_height too, the result is cropped to fill both.
image_heightalso thumb_height
16–4320
Resize the result to this height.
omit_backgroundalso transparent
true · falsedefault false
Transparent background (PNG and WebP) where the page sets none.
Block URLs matching these patterns, like *.example.com/widget*. Repeat the parameter or separate with commas.
block_resources
stylesheet · image · media · font · script · texttrack · xhr · fetch · eventsource · websocket · manifest · other
Block whole kinds of requests.
Your CSS, JS and clicks
Parameter
Values
What it does
hide_selectorsalso hide_selector
array
Hide elements matching these selectors. Repeat the parameter for several.
stylesalso css
string
CSS to add to the page before the capture.
scriptsalso js
string
JavaScript to run in the page before the capture; await works. If it throws, the call fails and isn’t billed.
click
string
Click the first element matching this selector, then wait for the page to settle.
Identity and location
Parameter
Values
What it does
dark_mode
true · false
true or false sets prefers-color-scheme; leave it out for the site’s default.
reduced_motion
true · falsedefault false
Set prefers-reduced-motion: reduce.
media_typealso media
screen · print
Emulate screen or print CSS.
user_agent
string
A user agent of your own. By default a current Chrome on Windows (or Android on mobile) is reported. Search and AI crawler user agents (Googlebot, bingbot, GPTBot, ClaudeBot and the like) aren’t allowed.
accept_languagealso accept_lang
stringdefault en-US,en;q=0.9
Accept-Language sent to the site.
headersalso header
array
Extra request headers as “Name: value”, sent only to the page’s own site. Repeat for several. A User-Agent header follows the user_agent rule.
cookiesalso cookie
array
Cookies as name=value, optionally with ; Domain=… ; Path=…. Repeat for several.
authorization
string
An Authorization header for the page’s own site, like Basic … or Bearer ….
timezonealso time_zone, tz
string
IANA time zone, like Europe/Berlin.
latitudealso geolocation_latitude
-90–90
Geolocation latitude (with longitude).
longitudealso geolocation_longitude
-180–180
Geolocation longitude.
PDF
Parameter
Values
What it does
pdf_paperalso pdf_paper_format
a3 · a4 · a5 · letter · legal · tabloiddefault a4
Paper size for format=pdf.
pdf_landscape
true · falsedefault false
Landscape pages.
pdf_backgroundalso pdf_print_background
true · falsedefault true
Print background colours and images.
pdf_margin
stringdefault 0.4in
Margin on every side, in px, mm, cm or in.
pdf_page_ranges
string
Only these pages, like 1-3,5.
Checks
Parameter
Values
What it does
fail_if_content_contains
array
Fail (not billed) if the page text contains this. Case-insensitive; repeat for several.
fail_if_content_missing
array
Fail (not billed) if the page text doesn’t contain this.
fallback
og
og: when a site blocks automated browsers, return its own share image instead of an error.
allow_blocked
true · falsedefault false
Return the capture even when it shows a bot check (still not billed).
Caching
Parameter
Values
What it does
cache
true · falsedefault false
Keep the result for 24 hours; the same request from your account within that time is served from the cache and isn’t billed.
cache_ttlalso ttl
0–2592000
Cache for this many seconds instead (up to 30 days). Implies cache=true; 0 turns caching off.
cache_key
string
Keep separate cached copies of the same request.
freshalso force
true · falsedefault false
Render again even when a cached copy exists.
Response and async
Parameter
Values
What it does
response_type
image · json · emptydefault image
image returns the file; json returns a file URL (kept 24 hours) with page metadata; empty returns only headers.
async
true · falsedefault false
Queue the render and answer at once with a job id (202). Poll /v1/jobs/{id} or add webhook_url.
webhook_urlalso webhook
string
We POST the result here when the job finishes, signed with your key’s signing secret. Implies async.
external_idalso external_identifier
string
Your own id, returned in the job and the webhook.
Response headers
X-Page-Verdict
ok, og (share image fallback) or blocked (with allow_blocked=true).
X-Billed
1 when this shot counted toward your plan, 0 when it didn’t.
X-Cache
HIT when served from your cache (never billed), MISS otherwise.
X-Render-Ms
How long the render took, in milliseconds.
X-Quota-Remaining
Clean shots left in this period.
X-RateLimit-Limit / X-RateLimit-Remaining
Your requests per minute, and how many are left in the current minute.
X-Page-Status
The HTTP status the captured page answered with.
X-Request-Id
The id of this render in your request log.
X-Ignored-Params
Parameters we didn’t recognise, so a typo doesn’t go unnoticed.
JSON responses
With response_type=json you get a link to the file (kept for 24 hours, or your cache time if longer) and what we read from the page:
Your selector, script or content check failed. Not billed.
422
url_not_allowed
The page redirected to a private address. Not billed.
429
rate_limited / concurrency_limit
Over your requests per minute, or too many renders at once. Retry-After says when.
502
navigation_failed / render_failed
The site couldn’t be loaded or rendered. Not billed.
504
timeout
The page didn’t finish within timeout. Not billed.
Limits and billing
Monthly quota: clean shots per period; the period starts on your subscription date (the calendar month on the free plan). We e-mail you at 80% and 100%.
Requests per minute and renders at once depend on the plan; over them you get 429 with Retry-After. Use async=true to queue big jobs instead.
Never billed: bot checks, blank pages, timeouts, failed loads, script or selector errors, content-check failures and cache hits.
Page size: full pages stop at 16,000 px; a page that downloads more than 60 MB stops loading and is captured as it is.
Signed links
Put a screenshot straight into an <img> without exposing a usable key: sign the query string with your key’s signing secret (HMAC-SHA256, hex) and add it as signature. Change any parameter and the signature stops matching. In the dashboard you can make a key accept signed requests only. A signed request is always a GET of /v1/shot with every option in the signed query string; every other endpoint, POST, bulk and MCP need a normal key.
const qs = new URLSearchParams({ access_key: KEY, url: 'https://example.com', format: 'webp' }).toString();
const signature = crypto.createHmac('sha256', SIGNING_SECRET).update(qs).digest('hex');
const src = `https://api.screenshotneo.com/v1/shot?${qs}&signature=${signature}`; // safe to put in an <img>
Async and webhooks
Add async=true (or a webhook_url) and the call returns 202 with a job id at once. Poll /v1/jobs/{id}, or let us POST the result to your webhook. Deliveries retry after 2 s, 15 s and 60 s and carry the same X-ScreenshotNeo-Delivery id each time; X-ScreenshotNeo-Signature is t=timestamp,v1=HMAC-SHA256(secret, timestamp + "." + body).
// Express: check the X-ScreenshotNeo-Signature header before trusting a webhook
const [t, v1] = req.get('x-screenshotneo-signature').split(',').map((p) => p.split('=')[1]);
const want = crypto.createHmac('sha256', SIGNING_SECRET).update(`${t}.${rawBody}`).digest('hex');
if (want !== v1 || Date.now() / 1000 - Number(t) > 300) return res.sendStatus(400);
// X-ScreenshotNeo-Delivery is the same on every retry: store it and drop repeats.
Most parameter names that other screenshot APIs use work here as they are: viewport_width, device_scale_factor, image_quality, thumbnail_width, css, js, wait_for, no_ads, no_cookie_banners, ttl, time_zone and more (listed under each parameter above). Change the host and the key, and check X-Ignored-Params for anything we don’t know yet.