Headless-Render-API

logo
PricingDocsSupportBlogSign In

Screenshot API

This document describes the screenshot functionality/endpoint, its associated HTTP header options, and possible error responses.

Endpoint: service.headless-render-api.com

Screenshot Path: /screenshot/$URL

Example URL: 

https://service.headless-render-api.com/screenshot/https://example.com/

The target $URL is obviously part of the path, but do not re-encode or re-escape it beyond what you'd enter into a browser URL field. Both UTF-8 encoding and percent-encoding are acceptable.

Related links: 

Auth

Send your secret API token (you'll get it after creating an account) as a header with all your requests to avoid rate limiting.
X-Prerender-Token
  • curl --header "X-Prerender-Token: secret-token"

Take screenshot of a webpage (URL)

A webpage screenshot API. Try it in your browser: service.headless-render-api.com/screenshot/https://example.com

cURL

curl https://service.headless-render-api.com/screenshot/https://example.com/ > out.png

Node.js client

// npm install prerendercloud
await prerendercloud.screenshot("https://example.com/", {
  deviceWidth: 800,
  deviceHeight: 600,
  viewportWidth: 640,
  viewportHeight: 480,
  viewportX: 0,
  viewportY: 0,
  format: "webp", // Default: png, other options: webp, jpeg
  // viewportQuerySelector: "#open-graph-div",
  // viewportQuerySelectorPadding: 10,
  // emulatedMedia: "screen",
  // viewportScale: 2, // Default: 1, min: 0.1, max: 3.0
  // isMobile: false, // Default: false, whether the meta viewport tag is taken into account
});

Optional HTTP Headers for Device Metrics

prerender-device-width
  • Overrides device screen width (default: 1366)
  • curl --header "prerender-device-width: 800"
prerender-device-height
  • Overrides device screen height (default: 768)
  • curl --header "prerender-device-height: 600"
prerender-device-is-mobile
  • Whether to emulate mobile device (default: false).

    This includes viewport meta tag, overlay scrollbars, text autosizing and more. In other words, whether the meta viewport tag is taken into account.

    an example of "viewport meta tag":
  • curl --header "prerender-device-is-mobile: true"

Optional HTTP Headers for Screenshots

prerender-viewport-query-selector
  • Specify a DOM element on the page to take a screenshot of, as opposed to the default of the entire window
  • curl --header "Prerender-Viewport-Query-Selector: #open-graph-div"
prerender-viewport-query-selector-padding
  • Use with query-selector option to add padding around the DOM element
  • curl --header "prerender-viewport-query-selector-padding: 10"
prerender-viewport-width
  • Width of viewport (screenshots only, not compatible with query selector)
  • curl --header "prerender-viewport-width: 100"
prerender-viewport-height
  • Height of viewport (screenshots only, not compatible with query selector)
  • curl --header "prerender-viewport-height: 100"
prerender-viewport-x
  • Viewport X offset in pixels (screenshots only, not compatible with query selector)
  • curl --header "prerender-viewport-x: 0"
prerender-viewport-y
  • Viewport Y offset in pixels (screenshots only, not compatible with query selector)
  • curl --header "prerender-viewport-y: 0"
prerender-viewport-scale
  • Page scale factor. Default: 1, min: 0.1, max: 3.0
  • curl --header "prerender-viewport-scale: 1.5"
prerender-screenshot-format
  • Default is png, choose from: jpeg, png, webp
  • curl --header "prerender-screenshot-format: webp"

Optional HTTP Headers for Browser Emulated Media

prerender-emulated-media
  • Emulates the given media type or media feature for CSS media queries

    default: screen

    Possible values are: screen, print, braille, embossed, handheld, projection, speech, tty, tv
  • curl --header "Prerender-Emulated-Media: screen"

Optional HTTP Headers for Headless-Render-API Server Behavior

prerender-wait-extra-long
  • Waits longer than normal for a page to finish rendering. Similar to Puppeteer's { waitUntil: 'networkidle' }. Useful for pages that depend on AJAX/XHR that fire late or IPFS hosted pages
  • curl --header "Prerender-Wait-Extra-Long: true"
prerender-dont-wait-for-web-sockets
  • By default, headless-render-api.com will wait for all ws activity to finish, but it doesn't make sense to "wait" for them to finish if they never stop. An example: real time prices on a stock price website.
  • curl --header "prerender-dont-wait-for-web-sockets: true"
prerender-block-cookies
  • By default, headless-render-api.com sends cookies back to the server. Use this to block them.
  • curl --header "prerender-block-cookies: true"

HTTP Error Codes

400
  • Invalid Request
  • There will be an error message in the HTML, fix your request and retry
  • Example causes:
    • malformed URL
    • a localhost URL/IP
    • or a page responds with content-type: application/octet-stream
429
  • Rate limited
  • Requests made without API tokens (or expired/missing billing information) will get this - see pricing
500
  • General Error
  • Example causes:
    • 10s (timeout) while waiting for a page to finish rendering (waits until all in-flight requests finish, load event, domContent event etc.)
    • or HTTPS Page is making HTTP (non secure) requests
    • ...or a random bug on our end
  • The error will show up in the headless-render-api.com web UI (after you sign in)
502
  • Bad Gateway (your origin returned 5xx)
  • It means we received a 5xx when trying to visit your page
  • Or it means we received a 403 (forbidden). Typically this means your page is behind a login wall or a firewall (like Cloudflare) is blocking the headless-render-api user-agent (make an exception to allow user-agents matching /prerendercloud/)
  • Probably not retryable. It depends on the site you're requesting. If it's your site, make sure it's up and running correctly
503
  • Over capacity (Rare)
  • Retry the request with some backoff
  • We'll see the error and our autoscaler will increase capacity within 5 minutes, but you should email us anyway: support@headless-render-api.com
504
  • Gateway Timeout (Rare)
  • Retry the request with some backoff
  • This is unexpected and should not happen. We'll see it, but you should email us anyway: support@headless-render-api.com