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. Only public http and https URLs are rendered: addresses in private or reserved networks and internal host names are refused with a 422 (see status codes).

Optional attributes

Name
format
Type
string
Description
The format of the file returned. Supported: jpg, jpeg, png, gif, webp (jpeg is treated as an alias for jpg), pdf and markdown. A gif is a single-frame image of at most 256 colours, made from a PNG capture: flat colours and text stay sharp, gradients show bands. 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 and webp; png and gif accept it and ignore it. Default value is 80.
Name
full_page
Type
boolean
Description
To take the screenshot of the full page, set full_page=1. 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
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); 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.
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:
- 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 Default value is load.
Name
block_cookie_banners
Type
boolean
Description
Whether to block cookie banners on the page. Set to 1 to enable, 0 to disable. Default value is 0, or 1 for markdown.
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.
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. At most 50 selectors of at most 255 characters each. Example: hide_selectors[]=.cookie-banner&hide_selectors[]=#newsletter-popup
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. Example: body { background-color: red !important; }
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. 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.

PDF attributes

These attributes apply to format=pdf only; other formats ignore them.

Name
pdf_paper_format
Type
string
Description
The paper size: A4, Letter, Legal or A3 (case-insensitive). 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 30 pages: ranges are cut at page 30, and longer documents end there.
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. pdf_page_ranges does not apply. 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. 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.

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, 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 (a long full_page at a high device_scale_factor) fails in the browser. Either way the API 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 page or viewport.

Response

By default, the response body is the file itself, served as a download: the image (image/png, image/jpeg, image/gif or image/webp) or the PDF (application/pdf). Markdown is returned as text/markdown; charset=UTF-8, or as JSON with response_type=json. 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. Responses with a PDF, with markdown or of HTML input always include them, also with upload=1; for image screenshots of a URL, the JSON response returned with upload=1 does not currently include them.

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.

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"

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 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 images, fonts, links and privacy.

Required attributes

Name
html
Type
string
Description
The HTML to render, at most 5 MB (5,242,880 bytes of UTF-8). 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.

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; send one of them, not both. 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