Take endpoint
On this page, we’ll dive into the take endpoint you can use to render a website, or your own HTML, as an image, a PDF or markdown.
AI coding agents: run curl -s https://screenshotbase.com/agents.md and follow it: an API key, the first call and the right plan, step by step.
Render a website
This endpoint renders a website and returns a screenshot, with format=pdf a PDF, or
with format=markdown the page's content as markdown. The PDF output and
URL to markdown guides explain these formats with examples.
Required attributes
- Name
url- Type
- string
- Description
The URL of the website you want to render, as you would open it in a browser: it is requested as sent, with percent-escapes, credentials and the fragment (
#/route,#:~:text=) kept, and an internationalized host name in its punycode form. Only public http and https URLs are rendered: addresses in private or reserved networks, internal host names, and port 0 and the ports browsers block (such as 22 or- are refused with a
422(see status codes). Maximum 8,192 characters.
- are refused with a
Optional attributes
- Name
format- Type
- string
- Description
The format of the file returned. Supported: jpg, jpeg, png, gif, webp, avif, svg (jpeg is treated as an alias for jpg), pdf, markdown and html. A gif is a single-frame image of at most 256 colors, made from a PNG capture: flat colors and text stay sharp, gradients show bands. An avif is at most 16,384 px on each side. An svg is the screenshot as a PNG inside an SVG of its size (no vectors), at most 16,384 px on each side. With html, the response is the rendered page's HTML (its DOM once it is ready, at most 20 MiB), served as a download in a sandbox; it costs one request, like markdown. With pdf, the page is printed as a PDF (see the PDF attributes below); with markdown, its content is returned as markdown (see the markdown attributes below). Default value is png.
- Name
quality- Type
- integer
- Description
The quality of the image returned, between 0 and 100. Applies to jpg, webp and avif; png, gif and svg accept it and ignore it (
max_file_sizemay lower it, seeX-Final-Quality). Default value is 80.
- Name
full_page- Type
- boolean
- Description
To take the screenshot of the full page, set full_page=1. The page is scrolled down first so that lazy-loaded images and content load (
full_page_scroll), a page that scrolls inside an element of its own is expanded, and up to 20,000 CSS px of it are captured (100,000 withasync=1, seefull_page_max_height). Not used for PDFs, which follow their paper size, or for markdown. Default value is 0.
- Name
viewport_width- Type
- integer
- Description
The width of the browser viewport in pixels, between 1 and 7,680. The browser's viewport is the window area where you can see the website. Default value is 1280.
- Name
viewport_height- Type
- integer
- Description
The height of the browser viewport in pixels, between 1 and 16,384. The browser's viewport is the window area where you can see the website. Together with
viewport_widthanddevice_scale_factorit is limited to 74,649,600 device pixels (see size limits). Default value is 800.
- Name
device_scale_factor- Type
- number
- Description
The device scale factor (device pixel ratio) used when rendering the page. Use 2 to emulate a retina/high-DPI display: the viewport size stays the same, but the returned image contains twice as many pixels in each dimension. Must be between 0.5 and 3. Default value is 1.
- Name
full_page_scroll- Type
- boolean
- Description
With
full_page, the page is scrolled down before the capture, so that lazy-loaded images and content load, then back to the top. It stops at the end of the page, atfull_page_max_heightor when the time limit of the render needs the rest. Set it to 0 to capture the page as it is after loading. Default value is 1.
- Name
full_page_scroll_delay- Type
- integer
- Description
Milliseconds to wait after each scroll step, between 0 and 5000. Default value is 100.
- Name
full_page_scroll_by- Type
- integer
- Description
CSS pixels per scroll step, between 100 and 16384. By default the viewport's height.
- Name
full_page_max_height- Type
- integer
- Description
The most of the page captured, in CSS pixels, between 1 and 20000 (up to 100,000 with
async=true). By default the maximum. A longer page is cut there and the response carriesX-Full-Page-Truncated: true.
- Name
full_page_scroll_container- Type
- string
- Description
A CSS selector of the element the page scrolls in, for pages laid out as an app shell, whose
htmlandbodyare as tall as the window. It is expanded to its content before the capture. Without it the largest such element is found by itself. Maximum 255 characters.
- Name
fix_sticky- Type
- boolean
- Description
Bars fixed to the bottom of the window are drawn at the end of the full page instead of in the middle of the image, and sticky elements where the page puts them. Default value is 1.
- Name
freeze_viewport_units- Type
- boolean
- Description
Keeps elements sized in viewport units (
vh,svh,dvhand the like) at the window's size during the capture. Default value is 0.
- Name
full_page_overflow- Type
- string
- Description
What happens to a full page larger than its format holds (see size limits):
scalecaptures it smaller to fit and the response carriesX-Full-Page-Scaledwith the scale,pngreturns it as a PNG,erroranswers422with the error codeoutput_too_large_for_format(not billed), also for a page taller thanfull_page_max_height. Default value is scale.
- Name
ip_country_code- Type
- string
- Description
The country code (ISO 3166-1 alpha-2) to use for the IP address when taking the screenshot. This allows you to simulate requests from different countries. Must be a lowercase code from the supported country list below — the value is case-sensitive, so use
us, notUS. Included in every paid plan. A free account can make 5 renders withip_country_codein any 5 days (a rolling window; a render counts when it starts, failed ones too, except those our proxy network refuses); after that the request answers403with the error codeplan_upgrade_requiredand the time the next one is available, and is not billed. When the proxy network will not load the website, the request answers422with the error codegeo_target_refused; when it has no capacity for the country,503withgeo_proxy_unavailableandRetry-After: 5. Neither is billed.
- Name
viewport_device- Type
- string
- Description
A device to emulate, by its id from GET /v1/devices (or its name). The render gets the device's viewport, device scale factor (at most 3), mobile and touch emulation and its browser's user agent.
viewport_width,viewport_height,device_scale_factor,viewport_mobileandviewport_has_touchreplace the device's values when you send them. Example:viewport_device=iphone-15-pro
- Name
viewport_mobile- Type
- boolean
- Description
Whether to emulate a mobile browser. Set to 1 to enable, 0 to disable. Default value is the device's, or 0.
- Name
viewport_has_touch- Type
- boolean
- Description
Whether to emulate a touch screen. Set to 1 to enable, 0 to disable. Default value is the device's, or 0.
- Name
viewport_landscape- Type
- boolean
- Description
Whether to turn the device to landscape (its width and height swapped). Default value is 0.
- Name
dark_mode- Type
- boolean
- Description
Set to 1 to render the page with
prefers-color-scheme: dark, 0 for light. Not set: the browser's default (light).
- Name
reduce_motion- Type
- boolean
- Description
Set to 1 to render the page with
prefers-reduced-motion: reduceand hold it still: animations and transitions end, videos pause and GIFs show their first frame. Default value is 0.
- Name
media_type- Type
- string
- Description
The CSS media type of a screenshot or markdown:
screenorprint. PDFs usepdf_media_type.
- Name
block_trackers- Type
- boolean
- Description
Whether to block known trackers (the host rules of EasyPrivacy). Default value is 0.
- Name
block_requests- Type
- array
- Description
URL patterns of requests to block;
*stands for any characters and a pattern matches the whole URL. At most 100 patterns of at most 2048 characters each. Example:block_requests[]=*.woff2&block_requests[]=https://ads.example.com/*
- Name
block_resources- Type
- array
- Description
Kinds of requests to block, comma separated: document (iframes), stylesheet, image, media, font, script, texttrack, xhr, fetch, prefetch, eventsource, manifest, ping, other. Example:
block_resources=image,font
- Name
proxy- Type
- string
- Description
Your own proxy for the render, as
scheme://user:password@host:port. The scheme ishttp,https(TLS to the proxy),socks5(host names resolve on our side) orsocks5h(host names resolve at the proxy). Without a port: 80 for http, 443 for https, 1080 for socks5 and socks5h. The user name and password go to the proxy only and are never logged; percent-encode@,:and/in them. A proxy on a private or internal network answers422with the error codeproxy_not_allowed; a proxy that cannot be reached, refuses the credentials or cannot connect to the website answers424withproxy_error. Neither is billed. Cannot be combined withip_country_code. Maximum 2,048 characters. Example:socks5h://user:password@proxy.example.com:1080
- Name
proxy_bypass_hosts- Type
- array
- Description
Hosts loaded directly instead of through
proxy: a host name or IP address, or*.and a domain for every host below it. You can pass several by using the parameter multiple times, with or without[]after the name; a single value is one host. At most 50 items of at most 255 characters each. Example:proxy_bypass_hosts=*.cdn.example.com&proxy_bypass_hosts=fonts.example.com
- Name
delay- Type
- integer
- Description
The delay in seconds to wait before taking the screenshot, the PDF or the markdown. Minimum value is 0, maximum value is 30, for every format and for HTML input (at most 7 through the MCP server). Default value is 0.
- Name
timeout- Type
- integer
- Description
The timeout in seconds for the page load. Minimum value is 5, maximum value is 105. Default value is 60. Every render must finish within 110 seconds of the start of the request, whatever this value: a longer timeout is cut to what is left (see time limit). Through the MCP server,
timeoutis at most 60 and a tool call must finish within about 12 seconds.
- Name
wait_until- Type
- string
- Description
Determines when the screenshot should be taken based on page load state. Supported values (case-insensitive):
load: Waits for the load event (entire page and all resources loaded)domcontentloaded: Waits for HTML document to be loaded and parsednetworkidle0: Waits until there are no active network connections for 500msnetworkidle2: Waits until there are no more than two active network connections for 500ms A list of up to 4 of them, comma separated (wait_until=load,networkidle0), waits for all. Default value is load.
- Name
platform_profile- Type
- string
- Description
desktoprenders as Chrome on Windows 11 does: its user agent, platform and client hints, and the Windows font names (Segoe UI, Calibri, Cambria, Consolas, ...) drawn with installed fonts of the same metrics or the closest look.linuxrenders as Chrome on Linux, with the renderer's own fonts. The response headerX-Render-Enginenames the browser version. Default value is desktop.
- Name
selector- Type
- string
- Description
A selector of the element to capture instead of the viewport (images only): CSS,
>>>to cross into shadow roots (#app >>> .chart) orpierce/(pierce/.chart). The element is waited for up to 5 seconds. Without one the viewport is captured, or the render fails with 422selector_not_found(the first 25 a day free, then billed 1) whenerror_on_selector_not_foundis true. Cannot be combined withfull_pageor theclip_*parameters. Maximum 1000 characters.
- Name
selector_scroll_into_view- Type
- boolean
- Description
Whether to scroll the element of
selectorinto view before capturing it. Set to 1 to enable, 0 to disable. Default value is 1.
- Name
error_on_selector_not_found- Type
- boolean
- Description
Whether a
selectorthat matches nothing fails the render (422selector_not_found, the first 25 a day free, then billed 1) instead of capturing the viewport. Default value is 0.
- Name
clip_x- Type
- integer
- Description
The left edge of the region to capture, in CSS pixels of the page (images only). Minimum value is 0, maximum value is 100000. Default value is 0.
- Name
clip_y- Type
- integer
- Description
The top edge of the region to capture, in CSS pixels of the page. Minimum value is 0, maximum value is 100000. Default value is 0.
- Name
clip_width- Type
- integer
- Description
The width of the region to capture. With
clip_heightthe image is that region of the page. Minimum value is 1, maximum value is 7680. Cannot be combined withfull_pageorselector.
- Name
clip_height- Type
- integer
- Description
The height of the region to capture.
clip_widthxclip_heightxdevice_scale_factor² must be at most 74,649,600 device pixels. Minimum value is 1, maximum value is 16384.
- Name
omit_background- Type
- boolean
- Description
Whether to capture without the browser's white background, so that a page without a background of its own comes out transparent. PNG and WebP only; other formats ignore it. Default value is 0.
- Name
wait_for_selector- Type
- string
- Description
A selector (CSS,
>>>,pierce/) to wait for before capturing, withintimeout. A wait that runs out answers 408target_timeout(the first 25 a day free, then billed 1). Maximum 1000 characters.
- Name
wait_for_selector_count- Type
- integer
- Description
How many elements must match
wait_for_selector, at least. Minimum value is 1, maximum value is 1000. Default value is 1.
- Name
fail_if_content_contains- Type
- array
- Description
Texts that fail the render when the page shows any of them (422
content_condition_failed, the first 25 a day free, then billed 1). Case and white space do not count. At most 20 texts of 1000 characters; repeat the parameter for more than one:fail_if_content_contains[]=Access denied&fail_if_content_contains[]=captcha.
- Name
fail_if_content_missing- Type
- array
- Description
Texts that fail the render when the page does not show one of them (422
content_condition_failed, the first 25 a day free, then billed 1). At most 20 texts of 1000 characters.
- Name
fail_if_request_failed- Type
- array
- Description
URL patterns: the render fails (424
request_failed, the first 25 a day free, then billed 1) when a request of the page whose URL matches one of them failed with a network error or an HTTP status of 400 or more. A pattern matches the whole URL,*standing for any characters:https://cdn.example.com/*,*.css. At most 20 patterns of 1000 characters.
- Name
actions- Type
- string
- Description
Steps to run on the page before it is captured, in order: a list of at most 20 step objects, best sent in the JSON body of a POST (in a GET as one JSON string). Each has a
typeand the fields of its type:click,hover(selector);type(selector,text: fills the field);press(key);select(selector,values);scroll(selector, orxand/ory);wait_for_selector(selector,state: attached, visible or hidden,count);wait(duration_ms);wait_for_navigation(wait_until);evaluate(code, at most 10 KB);click_accept(clicks the accept button of a cookie consent dialog);press_escape. Every step takesoptional(skip it instead of failing) andtimeout_ms(default 5000;wait_for_selectorandwait_for_navigationwait withintimeout). A step that cannot do what it says answers 422action_failednaming the step by its index and type (the first 25 a day free, then billed 1); once anevaluatestep or thescriptsran, any failure that is not ours is billed 1, since that code could read the page.X-Actions-Completedsays how many steps completed (an async job also asresult.actions). Actions cost nothing extra, and their texts are never logged.
- Name
scripts- Type
- string
- Description
JavaScript to run in the page after the actions, as the body of an async function. A script that throws answers 422
action_failed; once they ran, any failure that is not ours is billed 1. At most 50 KB (51,200 bytes).
- Name
scripts_wait_until- Type
- array
- Description
Only with
scripts: the events to wait for after them (one, or a list such asload,networkidle0).
- Name
block_ads- Type
- boolean
- Description
Whether to block ads on the page. Set to 1 to enable, 0 to disable. Default value is 0, or 1 for markdown.
- Name
block_chats- Type
- boolean
- Description
Whether to block chat widgets on the page. Set to 1 to enable, 0 to disable. Default value is 0. Hides the widgets of Intercom, LiveChat, Zendesk, Tawk.to, HubSpot, Drift, Crisp, Tidio, Freshchat, Olark, Zoho SalesIQ, Gorgias, Chatwoot, Help Scout, JivoChat, Smartsupp, Salesforce, Facebook Messenger and Shopify Inbox.
- Name
hide_selectors- Type
- array
- Description
An array of CSS selectors to hide on the page. Elements matching these selectors will be hidden using CSS display: none and visibility: hidden. You can pass multiple selectors by using the parameter multiple times, with or without
[]after its name; a single value is one selector. At most 50 selectors of at most 255 characters each. Example:hide_selectors=.cookie-banner&hide_selectors=#newsletter-popupAny CSS selector works, quoted attribute selectors and escapes included ([data-testid="banner"],.md\:hidden). Each selector applies on its own: one the browser cannot parse is skipped, and the others still apply. Elements inside iframes or shadow DOM are not reached.
- Name
styles- Type
- string
- Description
Custom CSS styles to inject into the page before taking the screenshot. This allows you to modify the page's appearance using any valid CSS. You should urlencode this value. Maximum 10,000 characters, valid UTF-8. Example:
body { background-color: red !important; }The CSS also applies on pages whose Content-Security-Policy blocks inline styles.@importrules load their style sheets; one that fails to load, or that the page's Content-Security-Policy refuses, is skipped, and the rest of the CSS still applies.
- Name
upload- Type
- boolean
- Description
When set to 1, the file is stored on our CDN (markdown as a
.mdfile) and the response is a JSON object containing its publicurlinstead of the file itself. Without it, the result is only sent back to you and not stored. A render costs the same with and without it. It takes a boolean such as 1, 0, true or false; anything else answers422. Default value is 0.
- Name
attachment_name- Type
- string
- Description
The filename (without extension) used for the downloaded file. The file extension is appended automatically based on the chosen format (
.mdfor markdown, which is returned inline unless you set this). Not used for JSON responses (upload=1, or markdown withresponse_type=json)./,\and control characters in the name are replaced by_. Maximum 255 characters.
- Name
diagnostics- Type
- boolean
- Description
When set to 1, the response is the render's diagnostics as JSON instead of the file: the status (
ok,partial,failed), the target's HTTP status and final URL, the time of each stage, request, console and network counts, whether a cookie banner was on screen, and a signed link, valid 24 hours, to a HAR of the page's requests (no bodies, cookies or credentials). Billed like the same request without it; not available withasync=1. Every render answers the headersX-Render-Status,X-Target-Status,X-Target-Final-Url,Server-Timing,X-Requests,X-Cookie-Banner,X-Images-PendingandX-Console-Errors. Default value is 0.
- Name
best_attempt- Type
- boolean
- Description
When set to 1, a page that does not finish loading in time is captured as it is instead of failing: the response carries
X-Render-Status: partialand is billed. A target that sends nothing of its page (or only a redirect) still fails with 408, not billed. Default value is 0.
- Name
ignore_host_errors- Type
- boolean
- Description
When set to 0, a target that answers with a bot challenge or block page (Cloudflare, Akamai, PerimeterX, DataDome, Imperva, AWS WAF, Kasada, Sucuri, Vercel or a CAPTCHA wall) or with an HTTP error status fails the request with 424 (
target_blockedwithblocked_by, ortarget_http_errorwithtarget_status), not billed, instead of capturing that page. Every render of a URL answersX-Target-Statusand, for a challenge or block page,X-Blocked-By. Default value is 1.
- Name
headers- Type
- array
- Description
Extra request headers, each as
Name: value, at most 50 and 8 KB together. Sent to the origin of the url only, unless headers_scope is all. Hop-by-hop headers, Host, Proxy-*, Content-Length and Expect are refused; use cookies (for Cookie, Set-Cookie and Cookie2), authorization, user_agent and accept_language instead of those headers. With headers, cookies or authorization the site needs a valid certificate, and ip_country_code an https url. Example:headers[]=X-Api-Key: abc&headers[]=X-Tenant: 7
- Name
headers_scope- Type
- string
- Description
Which requests get the headers: target (the origin of the url) or all (every request of the page, third parties included). Default value is target.
- Name
user_agent- Type
- string
- Description
The user agent of the browser. Maximum 512 characters.
- Name
time_zone- Type
- string
- Description
The time zone of the browser, such as Europe/Berlin.
- Name
locale- Type
- string
- Description
The locale of the browser, such as de-DE.
- Name
accept_language- Type
- string
- Description
The languages of the Accept-Language header, such as
de-DE,de;q=0.9. Maximum 256 characters.
- Name
geolocation_latitude- Type
- number
- Description
Latitude of the position the page's geolocation returns (https pages only), with geolocation_longitude.
- Name
geolocation_longitude- Type
- number
- Description
Longitude of that position, with geolocation_latitude.
- Name
geolocation_accuracy- Type
- number
- Description
Accuracy of that position in meters.
- Name
bypass_csp- Type
- boolean
- Description
Whether to ignore the page's Content-Security-Policy. Default value is 0.
PDF attributes
These attributes apply to format=pdf only; other formats ignore them.
- Name
pdf_paper_format- Type
- string
- Description
The paper size: A0, A1, A2, A3, A4, A5, A6, Letter, Legal, Tabloid (11 x 17 in) or Ledger (17 x 11 in), case-insensitive.
pdf_widthandpdf_heightset any other size. Default value is A4.
- Name
pdf_landscape- Type
- boolean
- Description
Set to 1 to print in landscape orientation. Default value is 0.
- Name
pdf_margin- Type
- string
- Description
The margin of every page as a CSS length in mm, cm, in or px (a bare number is px), for example
15mm. Two to four lengths set the sides as in the CSS margin shorthand:10mm 20mmis 10mm at the top and bottom and 20mm left and right. At most 4in per side. Default value is 0.
- Name
pdf_margin_top- Type
- string
- Description
The top margin as a CSS length; overrides
pdf_marginfor this side.pdf_margin_right,pdf_margin_bottomandpdf_margin_leftwork the same way.
- Name
pdf_print_background- Type
- boolean
- Description
Whether background colors and images are printed. Default value is 1.
- Name
pdf_media_type- Type
- string
- Description
printuses the page's print stylesheet, like "Save as PDF" in a browser;screenprints the page as it looks on screen. Default value is print.
- Name
pdf_scale- Type
- number
- Description
The scale of the page rendering, between 0.1 and 2. Default value is 1.
- Name
pdf_page_ranges- Type
- string
- Description
The pages to include, such as
1-3,5,8-(8-means page 8 to the end). A PDF has at most 200 pages: ranges are cut at page 200, and longer documents end there (the response then carriesX-Pdf-Truncated: pages).
- Name
pdf_fit_one_page- Type
- boolean
- Description
Set to 1 to print the whole page on a single PDF page as wide as the paper and as tall as the content, at most 200 inches; anything below is cut (
X-Pdf-Truncated: height).pdf_page_rangesdoes not apply. Default value is 0.
- Name
pdf_width- Type
- string
- Description
The page width as a CSS length in mm, cm, in or px, for example
210mm, instead of the paper format's; at most 200in.pdf_heightsets the height the same way. The margins must leave at least 1in of the page each way.
- Name
pdf_prefer_css_page_size- Type
- boolean
- Description
Set to 1 to print in the page size the page's own CSS sets (
@page { size: A5 }). Without it, the paper, size and orientation you set win over the page's CSS, and so do the margins you set. Default value is 0.
- Name
pdf_header_template- Type
- string
- Description
HTML printed at the top of every page, at most 16 KB, in the JSON body of a POST only.
{page},{total},{date},{title}and{url}are replaced. Laid out across the paper's width at 10px; the top margin is raised to at least 0.5in. Use inline styles anddata:images: a template that loads a style sheet or a web font answers 422.pdf_footer_templateprints at the bottom of every page the same way.
- Name
pdf_outline- Type
- boolean
- Description
Set to 1 to add a document outline (bookmarks) built from the page's headings. Default value is 0.
- Name
pdf_tagged- Type
- boolean
- Description
Whether the PDF is tagged (its structure for screen readers and text extraction); 0 writes a smaller file. Default value is 1.
Image size and output attributes
These attributes apply to images (jpg, png, gif, webp, avif and svg); a render with any of them is captured losslessly and encoded once at the end.
- Name
image_width- Type
- integer
- Description
The width of the returned image in pixels, between 1 and 16,384. Alone, the height follows the aspect ratio; together with
image_heightthe image is scaled to cover both and cropped from the top. Images only.
- Name
image_height- Type
- integer
- Description
The height of the returned image in pixels, between 1 and 16,384 (see
image_width).
- Name
max_file_size- Type
- integer
- Description
The most bytes the image may have, between 1024 and 52428800. jpg, webp and avif lower their quality first (the
X-Final-Qualityheader names the quality used), png and gif their colors; then the image gets smaller, down to a quarter of its size. If nothing fits, the answer is 422max_file_size_unreachable, not billed.
- Name
png_compression- Type
- integer
- Description
The zlib compression level of png (and the PNG inside an svg), between 0 and 9. Default value is 6.
- Name
png_palette- Type
- boolean
- Description
With 1, png and svg get a palette of at most 256 colors: much smaller for pages of flat colors and text. Default value is 0.
- Name
png_colors- Type
- integer
- Description
The most colors of the palette, between 2 and 256 (implies
png_palette).
- Name
preset- Type
- string
- Description
Sets the parameters of a common image that the request does not set itself:
og(1200 x 630),x_card(1200 x 600) andlinkedin(1200 x 627), each a jpg of at most 300,000 bytes, andthumbnail(a 1280 x 800 page as a 400 x 250 jpg of at most 50,000 bytes).
- Name
show_url- Type
- boolean
- Description
With 1, a strip on top of the image shows the page's URL (after redirects). Default value is 0.
- Name
show_timestamp- Type
- boolean
- Description
With 1, the strip on top of the image shows the time of the capture (UTC). Default value is 0.
Markdown attributes
These attributes apply to format=markdown only.
- Name
markdown_main_content_only- Type
- boolean
- Description
With 1, only the main content of the page is converted: the article, without navigation, sidebars, headers, footers and banners. With 0, the whole page body. Default value is 1.
- Name
response_type- Type
- string
- Description
textreturns the markdown astext/markdown;jsonreturns a JSON object withurl,title,descriptionandmarkdown. Does not apply withupload=1. For every other format,jsonstores the file asupload=1does and answersurl,width,height,bytesandformat(width and height are null for pdf and html); it is billed as the file would be. Default value is text.
Size limits
Parameters outside their range, such as a quality above 100 or more than 50
hide_selectors, answer 422 with an errors object before anything is rendered.
Parameters sent empty (quality=) or as null in a JSON body take their default.
Parameters the API does not know, misspelled ones included, are ignored: the request
is rendered (and billed) without them, so check the spelling if an option seems to have
no effect.
The viewport is limited to 74,649,600 device pixels: viewport_width x
viewport_height x device_scale_factor², which is 3,840 x 2,160 at
device_scale_factor 3, or 7,680 x 9,720 at 1.
An image can be larger than its format holds. Measured in device pixels (the
viewport, or the whole page with full_page, times device_scale_factor), a WebP is
at most 16,383 px on each side, an AVIF or SVG at most 16,384 px,
a JPEG at most 65,500 px, and a GIF at most 65,535 px and 25 megapixels in all. PNG has no limit of its own, but a capture of more than about
500 megapixels fails in the browser. A viewport capture larger than its format holds
answers 422 with the error code output_too_large_for_format and a message that names
the limit; the request is not billed. Use format=png, or a smaller viewport.
A full_page capture is scaled to fit its format instead, and the response carries
X-Full-Page-Scaled with the scale (full_page_overflow=scale, the default);
full_page_overflow=png returns a PNG instead and full_page_overflow=error answers the
422. At most 20,000 CSS px of the page are captured (100,000 with async=1;
full_page_max_height) and at most 16,384 CSS px of its width; a longer or wider page is
cut there and the response carries X-Full-Page-Truncated: true. A full page we encode
again after the capture (format=avif, gif or svg, image_width/image_height,
max_file_size, show_url/show_timestamp, png_* or a preset) is at most about 33.5
megapixels in device pixels (1,280 x 26,214 at device_scale_factor 1), other full pages
at most about 134 megapixels; a larger one is scaled to that the same way.
full_page scrolls the page down first, so that lazy-loaded images and content load,
then captures it in one piece. A page laid out as an app shell, whose html and body
are as tall as the window with the content scrolling inside an element of its own, is
expanded to its content first (full_page_scroll_container names the element when the
largest one is not it). Bars fixed to the bottom of the window are drawn at the end of the
page (fix_sticky).
Response
By default, the response body is the file itself, served as a download: the image
(image/png, image/jpeg, image/gif, image/webp, image/avif or
image/svg+xml), the PDF (application/pdf) or the page's HTML (text/html, with
Content-Security-Policy: sandbox). Markdown is returned as
text/markdown; charset=UTF-8, or as JSON with response_type=json; any other format
with response_type=json is stored and answered as JSON with its url, width,
height, bytes and format. If you pass upload=1, the result is stored and you receive a
JSON object with its public URL instead.
With async=1 the request answers 202 at once with a job, and the result is
rendered in the background (up to 300 seconds); see
Async Jobs & Webhooks.
Successful responses include the following headers, also with upload=1.
- Name
X-Cost- Type
- integer
- Description
The number of requests this call counted against your quota: 1 for a screenshot, a PDF or markdown, 0 for a PDF, markdown or a render of HTML input requested with a sandbox API key.
- Name
X-Execution-Time- Type
- number
- Description
Server-side processing time in milliseconds.
- Name
X-Concurrency-Limit- Type
- integer
- Description
The renders your plan may run at the same time (see concurrency).
- Name
X-Concurrency-Remaining- Type
- integer
- Description
The renders your plan may start right now, besides this one.
- Name
X-Render-Engine- Type
- string
- Description
The browser and its version that rendered, such as
chromium/154.0.8037.97, on every response, errors included. It changes when we update the browser.
- Name
X-Target-Status- Type
- integer
- Description
The HTTP status of the target page's document, after its redirects, on every render of a URL (errors included). A page of the target with a status of 400 or more is captured like any other unless
ignore_host_errors=0.
- Name
X-Full-Page-Truncated- Type
- string
- Description
truewhen afull_pagecapture was cut atfull_page_max_height(or 16,384 CSS px of width).
- Name
X-Full-Page-Scaled- Type
- string
- Description
The scale a
full_pagecapture was taken at to fit its format, such as0.7991.
- Name
X-Pdf-Truncated- Type
- string
- Description
Only for a PDF that was cut:
pageswhen it ends at the 200-page limit while the document goes on,heightwhenpdf_fit_one_pagereached 200 inches (see PDF output).
- Name
X-Final-Quality- Type
- integer
- Description
With
max_file_size: the quality a jpg, webp or avif ended at to fit.
- Name
X-Actions-Completed- Type
- string
- Description
With
actions: the steps completed of the steps sent, such as3/4, on every response of the render, errors included.
- Name
X-Render-Status- Type
- string
- Description
How the render went:
ok,partial(best_attempt=1captured a page that was not ready in time) orfailed, on every response of a render, errors included. With it comeX-Target-Final-Url(the page's URL after redirects),Server-Timing(the milliseconds of each stage),X-Requests(the page's requests: total, finished, failed, pending, blocked),X-Cookie-Banner(none,hiddenorvisible),X-Images-PendingandX-Console-Errors.diagnostics=1answers them as JSON, with a link to a HAR of the page's requests.
- Name
X-Blocked-By- Type
- string
- Description
Only for a bot challenge or block page: who served it (
cloudflare,akamai,perimeterx,datadome,imperva,aws_waf,kasada,sucuri,vercel, orcaptchafor a CAPTCHA wall). The page is captured and billed unlessignore_host_errors=0, which answers424target_blockedinstead.
Every response, errors included, carries an X-Request-Id header: the id of the
request in our logs. Include it when you contact support about a request.
Every render must finish within 110 seconds of the start of the request; a slower one
answers 408 and is not billed. A page that needs longer can be rendered as an
async job.
Error responses are returned as JSON with an error.code and the request_id — see
the status codes page for the full list of error codes and messages.
Request
curl -G "https://api.screenshotbase.com/v1/take?url=https%3A%2F%2Fbbc.com" \
-H "apikey: YOUR-API-KEY" \
-o bbc.png
PDF (cURL)
curl -G https://api.screenshotbase.com/v1/take \
-H "apikey: YOUR-API-KEY" \
--data-urlencode "url=https://example.com" \
-d format=pdf \
-d pdf_margin=15mm \
-o page.pdf
Markdown (cURL)
curl -G https://api.screenshotbase.com/v1/take \
-H "apikey: YOUR-API-KEY" \
--data-urlencode "url=https://example.com" \
-d format=markdown \
-d response_type=json
Response (upload=1)
{
"url": "https://cache.screenshotbase.com/screenshots/1337/01JA2Y6K7Q9W4V8T5R3N1M0P2Z.png"
}
Error response
{
"message": "The target website took too long to load.",
"error": {
"code": "target_timeout",
"message": "The target website took too long to load."
},
"request_id": "3f1c9a52-6d0e-4b7a-9c1e-2b8f5d4a7e10"
}
Render HTML
This endpoint renders HTML (or markdown) that you send in a JSON body, instead of a URL, and returns it as a screenshot, a PDF or markdown. The Render HTML guide covers markdown input, images, fonts, links and privacy.
Required attributes
- Name
html- Type
- string
- Description
The HTML to render, at most 10 MB (10,485,760 bytes of UTF-8), with
async=150 MB. It is rendered as an https page whose relative URLs do not resolve: use absolute URLs, a base element ordata:URLs. Only accepted in the request body. Instead ofhtml(orurl) you can sendmarkdown.
- Name
markdown- Type
- string
- Description
Markdown to render instead of
html, at most 1 MB (1,048,576 bytes of UTF-8), in GitHub's flavor (tables, task lists, strikethrough, autolinks). It is rendered as an HTML page with a readable default style, whichstylescan change. Raw HTML in the markdown is kept; relative URLs do not resolve. Only accepted in the request body.
Optional attributes
Every attribute of GET /v1/take works as a JSON field, for
example format, viewport_width, hide_selectors (an array), the
PDF attributes, the markdown attributes
and upload, as well as async for an async job. Instead of html you
can also send url or markdown; send exactly one of them. With url, the request
works like GET /v1/take with the same options.
Response
The same as for GET /v1/take: the file, or a JSON object with its public url when
upload is true. Every successful render of HTML counts as one request, also with
upload, and includes the X-Cost and X-Execution-Time headers. It must finish
within 110 seconds of the start of the request; a slower render answers 408 and is
not billed.
Request
curl https://api.screenshotbase.com/v1/take \
-H "apikey: YOUR-API-KEY" \
-H "Content-Type: application/json" \
-d '{"html": "<h1>Invoice INV-42</h1>", "format": "pdf", "upload": true}'
Response (upload: true)
{
"url": "https://cache.screenshotbase.com/screenshots/1337/01JA2Y6K7Q9W4V8T5R3N1M0P2Z.pdf"
}
Supported countries
The ip_country_code parameter accepts the following lowercase ISO 3166-1 alpha-2
country codes. The value is case-sensitive — uppercase codes are rejected with a
422 validation error.
Supported ip_country_code values
ae, al, am, ar, at, au, az, ba, bd, be, bg, bh, bn, bo, br, bw, by, ca, cg, ch,
cl, cm, cn, co, cr, cy, cz, de, dk, do, dz, ec, ee, eg, es, fi, fr, gb, ge, gh,
gr, gt, hk, hr, hu, id, ie, il, im, in, iq, is, it, jm, jo, jp, ke, kg, kh, kr,
kw, kz, la, li, lk, lt, lu, lv, ma, md, mk, mm, mo, mw, mx, my, mz, ng, nl, no,
nz, om, pa, pe, ph, pk, pl, pr, pt, py, qa, ro, rs, ru, sa, sc, se, sg, si, sk,
sl, th, tj, tm, tn, tr, tw, tz, ua, us, uy, uz, ve, vn, za, zm, zw