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.


GET/v1/take

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

    1. are refused with a 422 (see status codes). Maximum 8,192 characters.

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_size may lower it, see X-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 with async=1, see full_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_width and device_scale_factor it 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, at full_page_max_height or 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 carries X-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 html and body are 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, dvh and 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): scale captures it smaller to fit and the response carries X-Full-Page-Scaled with the scale, png returns it as a PNG, error answers 422 with the error code output_too_large_for_format (not billed), also for a page taller than full_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, not US. Included in every paid plan. A free account can make 5 renders with ip_country_code in 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 answers 403 with the error code plan_upgrade_required and the time the next one is available, and is not billed. When the proxy network will not load the website, the request answers 422 with the error code geo_target_refused; when it has no capacity for the country, 503 with geo_proxy_unavailable and Retry-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_mobile and viewport_has_touch replace 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: reduce and 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: screen or print. PDFs use pdf_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 is http, https (TLS to the proxy), socks5 (host names resolve on our side) or socks5h (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 answers 422 with the error code proxy_not_allowed; a proxy that cannot be reached, refuses the credentials or cannot connect to the website answers 424 with proxy_error. Neither is billed. Cannot be combined with ip_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, timeout is 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 parsed
    • networkidle0: Waits until there are no active network connections for 500ms
    • networkidle2: 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

    desktop renders 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. linux renders as Chrome on Linux, with the renderer's own fonts. The response header X-Render-Engine names 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) or pierce/ (pierce/.chart). The element is waited for up to 5 seconds. Without one the viewport is captured, or the render fails with 422 selector_not_found (the first 25 a day free, then billed 1) when error_on_selector_not_found is true. Cannot be combined with full_page or the clip_* parameters. Maximum 1000 characters.

  • Name
    selector_scroll_into_view
    Type
    boolean
    Description

    Whether to scroll the element of selector into 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 selector that matches nothing fails the render (422 selector_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_height the image is that region of the page. Minimum value is 1, maximum value is 7680. Cannot be combined with full_page or selector.

  • Name
    clip_height
    Type
    integer
    Description

    The height of the region to capture. clip_width x clip_height x device_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, within timeout. A wait that runs out answers 408 target_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 type and the fields of its type: click, hover (selector); type (selector, text: fills the field); press (key); select (selector, values); scroll (selector, or x and/or y); 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 takes optional (skip it instead of failing) and timeout_ms (default 5000; wait_for_selector and wait_for_navigation wait within timeout). A step that cannot do what it says answers 422 action_failed naming the step by its index and type (the first 25 a day free, then billed 1); once an evaluate step or the scripts ran, any failure that is not ours is billed 1, since that code could read the page. X-Actions-Completed says how many steps completed (an async job also as result.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 as load,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-popup Any 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. @import rules 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 .md file) and the response is a JSON object containing its public url instead 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 answers 422. 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 (.md for markdown, which is returned inline unless you set this). Not used for JSON responses (upload=1, or markdown with response_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 with async=1. Every render answers the headers X-Render-Status, X-Target-Status, X-Target-Final-Url, Server-Timing, X-Requests, X-Cookie-Banner, X-Images-Pending and X-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: partial and 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_blocked with blocked_by, or target_http_error with target_status), not billed, instead of capturing that page. Every render of a URL answers X-Target-Status and, 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
    cookies
    Type
    array
    Description

    Cookies for the url, each as a Set-Cookie value: session=abc; Path=/; Secure; HttpOnly. At most 50 cookies of at most 4 KB each. A Domain must be the url's host or a parent domain of it.

  • Name
    authorization
    Type
    string
    Description

    An Authorization header (Basic or Bearer) for the origin of the url only, sent with the first request. Example: Basic dXNlcjpwYXNz

  • 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_width and pdf_height set 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 20mm is 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_margin for this side. pdf_margin_right, pdf_margin_bottom and pdf_margin_left work 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

    print uses the page's print stylesheet, like "Save as PDF" in a browser; screen prints 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 carries X-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_ranges does 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_height sets 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 and data: images: a template that loads a style sheet or a web font answers 422. pdf_footer_template prints 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_height the 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-Quality header 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 422 max_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) and linkedin (1200 x 627), each a jpg of at most 300,000 bytes, and thumbnail (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

    text returns the markdown as text/markdown; json returns a JSON object with url, title, description and markdown. Does not apply with upload=1. For every other format, json stores the file as upload=1 does and answers url, width, height, bytes and format (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

    true when a full_page capture was cut at full_page_max_height (or 16,384 CSS px of width).

  • Name
    X-Full-Page-Scaled
    Type
    string
    Description

    The scale a full_page capture was taken at to fit its format, such as 0.7991.

  • Name
    X-Pdf-Truncated
    Type
    string
    Description

    Only for a PDF that was cut: pages when it ends at the 200-page limit while the document goes on, height when pdf_fit_one_page reached 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 as 3/4, on every response of the render, errors included.

  • Name
    X-Render-Status
    Type
    string
    Description

    How the render went: ok, partial (best_attempt=1 captured a page that was not ready in time) or failed, on every response of a render, errors included. With it come X-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, hidden or visible), X-Images-Pending and X-Console-Errors. diagnostics=1 answers 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, or captcha for a CAPTCHA wall). The page is captured and billed unless ignore_host_errors=0, which answers 424 target_blocked instead.

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

GET
/v1/take
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"
}

POST/v1/take

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=1 50 MB. It is rendered as an https page whose relative URLs do not resolve: use absolute URLs, a base element or data: URLs. Only accepted in the request body. Instead of html (or url) you can send markdown.

  • 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, which styles can 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

POST
/v1/take
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