Options Reference

Basic Options

url

The URL of the website you want to screenshot

Examples
url=bbc.co.uk

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk"}'

Result

Downloading image...

url=apple.com

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com"}'

Result

Downloading image...

url=google.com

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"google.com"}'

Result

Downloading image...


width

default: 1280

Viewport width of the browser in pixels

Examples
width=320

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com","width":320}'

Result

Downloading image...

width=768

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com","width":768}'

Result

Downloading image...

width=1280

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com","width":1280}'

Result

Downloading image...


height

default: 1024

Viewport height of the browser in pixels

Examples
height=400

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com","height":400}'

Result

Downloading image...

height=800

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com","height":800}'

Result

Downloading image...

height=1400

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"apple.com","height":1400}'

Result

Downloading image...


full_page

default: false

Specify whether to capture the full scrollable area of the website. For PDF's, full_page mode will attempt to capture the whole website onto one single page pdf document.

Example
full_page=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","full_page":true}'

Result

Downloading image...


selector

Take a screenshot of the element that matches this selector. By default, if the selector is not found, Urlbox will take a normal viewport screenshot. If you prefer Urlbox to fail the request when the selector is not found, pass fail_if_selector_missing=true.

Example
selector=#trynow

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","selector":"#trynow"}'

Result

Downloading image...


Blocking Options

Options relating to blocking of certain page elements such as cookie banners

block_ads

Blocks requests from popular ad-networks from loading

Examples
block_ads=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","block_ads":true}'

Result

Downloading image...

block_ads=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","block_ads":false}'

Result

Downloading image...


Automatically hide cookie banners from most websites

Examples
hide_cookie_banners=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk","hide_cookie_banners":true}'

Result

Downloading image...

hide_cookie_banners=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk","hide_cookie_banners":false}'

Result

Downloading image...


click_accept

Automatically click accept buttons in order to hide popups

Examples
click_accept=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk","click_accept":true}'

Result

Downloading image...

click_accept=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk","click_accept":false}'

Result

Downloading image...


hide_selector

Comma delimited string of css element selectors that are hidden by setting their style to display: none!important;. Useful for hiding popups.


Customize Options

Customize the look of the page before rendering a screenshot

js

Inject and execute custom javascript on the page


css

Inject custom css into the page


Image Options

Options relating to the outputted PNG, WebP or JPEG file

retina

default: false

Take a 'retina' or high definition screenshot equivalent to setting a device pixel ratio of 2.0 or @2x. Please note that retina screenshots will be double the normal dimensions and will normally take slightly longer to process due to the much bigger image size.

Examples
retina=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","retina":true}'

Result

Downloading image...

retina=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","retina":false}'

Result

Downloading image...


thumb_width

Width in pixels of the generated thumbnail, leave off for full-size screenshot

Examples
thumb_width=100

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","thumb_width":100}'

Result

Downloading image...

thumb_width=200

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","thumb_width":200}'

Result

Downloading image...

thumb_width=400

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","thumb_width":400}'

Result

Downloading image...


thumb_height

Height in pixels of the generated thumbnail, leave off for full-size screenshot

Examples
thumb_height=100

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","thumb_height":100}'

Result

Downloading image...

thumb_height=200

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","thumb_height":200}'

Result

Downloading image...

thumb_height=400

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","thumb_height":400}'

Result

Downloading image...


quality

default: 80

JPEG/WebP only - image quality of resulting screenshot (0-100)

Examples
quality=40

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"spotify.com","quality":40}'

Result

Downloading image...

quality=80

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"spotify.com","quality":80}'

Result

Downloading image...

quality=100

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"spotify.com","quality":100}'

Result

Downloading image...


transparent

default: false

If a website has no background color set, the image will have a transparent background (PNG/WebP only)


max_height

For extremely lengthy websites it may be preferable to limit the screenshot to a maximum height to prevent Urlbox from spending time scrolling and generating an enormous screenshot


download

Pass in a filename e.g. download=myfilename.png which sets the content-disposition header on the response. This will make the urlbox link a downloadable link and prompt the user to save the file as myfilename.png.


PDF Options

Options relating to PDF document generation

pdf_page_size

default: A4

Sets the pdf page size. Options are

  • A0
  • A1
  • A2
  • A3
  • A4
  • A5
  • A6
  • Legal
  • Letter
  • Ledger
  • Tabloid

Setting this option will take precedence over pdf_page_width and pdf_page_height.

Examples
pdf_page_size=A0

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"format":"pdf","url":"example.com","pdf_page_size":"A0"}'

Result

Downloading image...

pdf_page_size=A4

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"format":"pdf","url":"example.com","pdf_page_size":"A4"}'

Result

Downloading image...

pdf_page_size=Letter

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"format":"pdf","url":"example.com","pdf_page_size":"Letter"}'

Result

Downloading image...


pdf_page_width

Sets the pdf page width in pixels


pdf_page_height

Sets the pdf page height in pixels


pdf_margin

default: None

Set the margin of the PDF document. Available options are

  • none
  • default
  • minimum
Examples
pdf_margin=none

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin":"none"}'

Result

Downloading image...

pdf_margin=default

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin":"default"}'

Result

Downloading image...

pdf_margin=minimum

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin":"minimum"}'

Result

Downloading image...


pdf_margin_top

Set a custom top pdf margin

Example
pdf_margin_top=40

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin_top":40}'

Result

Downloading image...


pdf_margin_right

Set a custom right pdf margin

Example
pdf_margin_right=100

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin_right":100}'

Result

Downloading image...


pdf_margin_bottom

Set a custom bottom pdf margin

Example
pdf_margin_bottom=50

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin_bottom":50}'

Result

Downloading image...


pdf_margin_left

Set a custom left pdf margin

Example
pdf_margin_left=60

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_margin_left":60}'

Result

Downloading image...


pdf_scale

default: 1

Scale factor of the website content. Valid values are numbers between 0.1 and 2

Examples
pdf_scale=0.2

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_scale":0.2}'

Result

Downloading image...

pdf_scale=1.2

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_scale":1.2}'

Result

Downloading image...

pdf_scale=2

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_scale":2}'

Result

Downloading image...


pdf_orientation

default: Portrait

Sets the pdf document orientation, options are

  • portrait
  • landscape
Examples
pdf_orientation=portrait

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_orientation":"portrait"}'

Result

Downloading image...

pdf_orientation=landscape

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","format":"pdf","pdf_orientation":"landscape"}'

Result

Downloading image...


pdf_background

default: true

Sets whether to print background images in the PDF

Examples
pdf_background=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.com","format":"pdf","pdf_background":true}'

Result

Downloading image...

pdf_background=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.com","format":"pdf","pdf_background":false}'

Result

Downloading image...


disable_ligatures

Prevent ligatures from being used. Useful when rendering a pdf and you want to extract text which contains ligatures.

Examples
disable_ligatures=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://kubla.fi/yhteystiedot/","format":"pdf","disable_ligatures":true}'

Result

Downloading image...

disable_ligatures=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://kubla.fi/yhteystiedot/","format":"pdf","disable_ligatures":false}'

Result

Downloading image...


media

default: print

By default, when generating a pdf, the print css media query is used. To generate a pdf using the screen css, set this option to screen

Examples
media=screen

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk","format":"pdf","media":"screen"}'

Result

Downloading image...

media=print

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"bbc.co.uk","format":"pdf","media":"print"}'

Result

Downloading image...


Cache Options

Control how Urlbox caches your screenshots or pdf documents

force

default: false

Generate a fresh screenshot or pdf instead of getting a cached version


unique

You can pass a unique string such as a UUID, hash or timestamp to have more control over when to generate a fresh screenshot or pdf.For example unique = 1624467216958


ttl

default: 2592000 (30 days)

Short for 'time to live'. Number of seconds to keep a screenshot or pdf in the cache. Note the default is also the maximum value for this option.

Examples
1 day

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","ttl":86400}'

Result

Downloading image...

1 week

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","ttl":604800}'

Result

Downloading image...

1 month

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","ttl":2592000}'

Result

Downloading image...


Request Options

Options to configure the browser before navigating to the URL

proxy

Pass in an address to a proxy server to make screenshot requests via that server in the format [address]:[port].

If proxy authentication is needed you can use the following format: [user]:[password]@[address]:[port].


Sets a header on the request when loading the URL.

To set the header with key X-My-Header to the value SomeValue, you would pass header=X-My-Header%3DSomeValue.

Can be set multiple times to set more than one header e.g. header=X-My-Header%3DSomeValue&header=X-My-Other-Header%3DSomeOtherValue.

As with all options passed via the query string, the header value must be URL encoded so X-My-Header=SomeValue becomes X-My-Header%3DSomeValue in order to be interpreted correctly by Urlbox

Examples
header=X-My-Header=MyHeaderValue

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-http-headers-is-my-browser-sending","full_page":true,"block_ads":true,"header":"X-My-Header=MyHeaderValue"}'

Result

Downloading image...

Setting multiple headers

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-http-headers-is-my-browser-sending","full_page":true,"block_ads":true,"header":["X-Header-1=valueOfHeader1","X-Header-2=valueOfHeader2"]}'

Result

Downloading image...


Sets a cookie on the request when loading the URL.

To set the cookie with key Opt-In to the value yes, you would pass cookie=Opt-In%3Dyes.

Can be set multiple times to set more than one cookie e.g.cookie=Opt-In%3Dyes&cookie=Session-Id%3DMTIzNDU.

As with all options passed in the query string, the cookie value must be URL encoded so OptIn=true becomes OptIn%3Dtrue in order to be interpreted correctly by Urlbox

Examples
cookie=OptIn=yes

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-http-headers-is-my-browser-sending","full_page":true,"block_ads":true,"cookie":"OptIn=yes"}'

Result

Downloading image...

Setting multiple cookies

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-http-headers-is-my-browser-sending","full_page":true,"block_ads":true,"cookie":["OptIn=yes","BestScreenshots=urlbox"]}'

Result

Downloading image...


user_agent

Use this option to set the User-Agent string for the request

The presets are:

  • random - Uses a random user-agent to help avoid bot detection
  • mobile - Uses a mobile like user-agent string
  • desktop - Uses a desktop user-agent string This can be used in some cases to emulate certain device types like mobile phones or tablets.
Examples
user_agent=random

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-is-my-user-agent","block_ads":true,"user_agent":"random"}'

Result

Downloading image...

user_agent=mobile

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-is-my-user-agent","block_ads":true,"user_agent":"mobile"}'

Result

Downloading image...

user_agent=desktop

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-is-my-user-agent","block_ads":true,"user_agent":"desktop"}'

Result

Downloading image...

Google bot

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-is-my-user-agent","block_ads":true,"user_agent":"Googlebot/2.1 (+http://www.google.com/bot.html)"}'

Result

Downloading image...

Facebook crawler

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-is-my-user-agent","block_ads":true,"user_agent":"facebookexternalhit/1.1"}'

Result

Downloading image...

Custom

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-is-my-user-agent","block_ads":true,"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 11_2_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/89.0.4389.90 Safari/537.36"}'

Result

Downloading image...


accept_lang

default: en-US

Sets an Accept-Language header on requests to the target URL

Examples
accept_lang=de-CH

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"microsoft.com","accept_lang":"de-CH"}'

Result

Downloading image...

accept_lang=ko-KR

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"microsoft.com","accept_lang":"ko-KR"}'

Result

Downloading image...


authorization

Sets an Authorization header on requests to the target URL. Can be used to pass an auth token through to the site in order to 'login' before rendering.

Examples
authorization=Basic my_base64_auth_token

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-http-headers-is-my-browser-sending","full_page":true,"block_ads":true,"authorization":"Basic my_base64_auth_token"}'

Result

Downloading image...

authorization=Bearer my_bearer_token

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/what-http-headers-is-my-browser-sending","full_page":true,"block_ads":true,"authorization":"Bearer my_bearer_token"}'

Result

Downloading image...


tz

Set local timezone to use for the screenshot e.g. tz=Europe/London. Default is UTC

Examples
tz=Europe/London

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.google.com/search?q=what+is+my+timezone","tz":"Europe/London"}'

Result

Downloading image...

tz=America/New_York

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.google.com/search?q=what+is+my+timezone","tz":"America/New_York"}'

Result

Downloading image...


Wait Options

delay

Amount of time to wait in milliseconds before urlbox takes the screenshot or pdf


timeout

default: 30000

Amount of time to wait in milliseconds for the requested URL to respond


wait_until

Instruct urlbox to continue processing once

Examples
wait_until=domloaded

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","wait_until":"domloaded"}'

Result

Downloading image...

wait_until=mostrequestsfinished

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","wait_until":"mostrequestsfinished"}'

Result

Downloading image...

wait_until=requestsfinished

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","wait_until":"requestsfinished"}'

Result

Downloading image...

wait_until=loaded

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"example.com","wait_until":"loaded"}'

Result

Downloading image...


wait_for

Waits for the element specified by this selector to be present in the dom before taking a screenshot or pdf.

By default Urlbox will take a screenshot or pdf if the wait_for element is not found after waiting for the time specified by the wait_timeout option.

If you prefer Urlbox to fail the request when the wait_for element is not found, pass fail_if_selector_missing=true


wait_to_leave

Waits for the element specified by this selector to be absent from the dom before taking a screenshot or pdf.

An example would be waiting for long running loading spinners to be gone before taking a screenshot.

By default Urlbox will take a screenshot or pdf if the wait_to_leave element is still present after the time specified by the wait_timeout option.

If you prefer Urlbox to fail the request when the wait_to_leave element is still present, pass fail_if_selector_present=true


wait_timeout

default: 30000

How many milliseconds Urlbox should wait for the wait_for element to be available before continuing


Page Options

Options which modify the page state before taking a screenshot or pdf

scroll_to

Scroll to either an element or pixel offset from the top before taking a screenshot

Examples
scroll_to=#trynow

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","scroll_to":"#trynow"}'

Result

Downloading image...

scroll_to=1024

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","scroll_to":1024}'

Result

Downloading image...

scroll_to=5000

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","scroll_to":5000}'

Result

Downloading image...


click

Element selector that is clicked before generating a screenshot or pdf e.g. #clickme would click the element with id="clickme".

Can be used multiple times to simulate multiple sequential click events.

If the selector matches multiple elements, only the first element will be clicked


click_all

Element selector that is clicked before generating a screenshot or pdf e.g. #clickme would click the element with id="clickme".

Can be used multiple times to simulate multiple sequential click events.

If the selector matches multiple elements, all elements will be clicked


hover

Element selector that is hovered before generating a screenshot or pdf e.g. #hoverme would hover over the element with id="hoverme"


bg_color

Hex code or css color string. Some websites don't set a body background colour, and will show up as transparent backgrounds with PNG or black when using JPG. Use this setting to set a background colour. If the website explicitly sets a transparent background on the html or body elements, this setting will be overridden.


disable_js

default: false

Turns off javascript on target url.

Examples
disable_js=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","disable_js":true}'

Result

Downloading image...

disable_js=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"nytimes.com","disable_js":false}'

Result

Downloading image...


flash

default: false

Enable the flash plugin for flash using websites

Examples
flash=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/is-flash-installed","block_ads":true,"flash":true}'

Result

Downloading image...

flash=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.whatismybrowser.com/detect/is-flash-installed","block_ads":true,"flash":false}'

Result

Downloading image...


Full Page Options

Advanced options that control how Urlbox takes full page screenshots, when full_page=true

allow_infinite

By default when Urlbox detects an infinite scrolling page, it does not attempt to continue scrolling until the bottom, as this could result in infinite scrolling! If you want to override this behaviour pass true for this option


skip_scroll

default: false

Enabling skip_scroll will speed up renders by skipping an initial scroll through the page which is used to trigger any lazy loading elements.

Examples
skip_scroll=true

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","full_page":true,"skip_scroll":true}'

Result

Downloading image...

skip_scroll=false

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"urlbox.io","full_page":true,"skip_scroll":false}'

Result

Downloading image...


detect_full_height

Some pages have full-height backgrounds whose heights are set to 100% of the viewport. This can cause the backgrounds to get stretched when making a full page screenshot. If you are seeing this behaviour in your full page screenshots, pass true for this option.


max_section_height

default: 4096

When Urlbox takes a full_page screenshot, the maximum height of each image section is set as 4096 pixels. If a site is greater than this value, Urlbox will start splitting the screenshot into sections. Sometimes it is worthwhile to experiment with this number


scroll_increment

When scrolling the page to trigger lazy loading elements, decide by how many pixels the page should be scrolled by. By default the scroll increment is set to the browser viewport height. Some pages lazy loading elements however only trigger when the scroll increment is smaller than this e.g. 400px


scroll_delay

When Urlbox decides to split a screenshot into multiple sections, the scroll delay is the time (in milliseconds) between taking the screenshots of each individual section. Whilst Urlbox does detect animations and attempts to wait for them before taking a screenshot, this option could be used to force urlbox to wait for a certain amount of time after scrolling to the next section, to wait for things like animations to finish.


turbo

Warning - experimental option. Used to speed up full page screenshots but at the expense of less accuracy.


Highlight word Options

Optionally highlight a word on the page

highlight

Word to highlight on the page before capturing a screenshot or pdf


highlightfg

default: white

Text color of the highlighted word


highlightbg

default: red

Background color of the highlighted word


Geolocation Options

Set the geolocation API co-ordinates

latitude

Latitude used to emulate the Geolocation API

Example
latitude=74.006

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.infobyip.com/browsergeolocation.php","longitude":40.7128,"latitude":74.006}'

Result

Downloading image...


longitude

Longitude used to emulate the Geolocation API

Example
longitude=40.7128

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.infobyip.com/browsergeolocation.php","latitude":74.006,"longitude":40.7128}'

Result

Downloading image...


accuracy

How accurate the Geolocation API should be in meters

Examples
accuracy=100

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.infobyip.com/browsergeolocation.php","latitude":74.006,"longitude":40.7128,"accuracy":100}'

Result

Downloading image...

accuracy=5000

Example urlbox GET request:

Example urlbox POST request:

curl -X POST \
https://api.urlbox.io/v1/render \
-H 'Authorization: Bearer your-urlbox-secret' \
-H 'Content-Type: application/json' \
-d '{"url":"https://www.infobyip.com/browsergeolocation.php","latitude":74.006,"longitude":40.7128,"accuracy":5000}'

Result

Downloading image...


Storage Options

Options relating to storing the screenshots in S3

use_s3

default: false

Save the screenshot directly to the S3 bucket configured on your account


s3_path

The s3 path, including subdirectories and the filename, to save the screenshot to in your S3 bucket. The extension (.png, .jpg or .pdf) will be provided automatically and should not be included in s3_path.


s3_bucket

Override the configured s3 bucket that the screenshot will be saved to


s3_storageclass

default: standard

Set the s3 storage class, options are

  • standard
  • standard_ia
  • reduced_redundancy
  • onezone_ia
  • intelligent_tiering
  • glacier
  • deep_archive
  • outposts

Request Behaviour Options

Dictate how Urlbox handles certain scenarios

fail_if_selector_missing

default: false

Fails the request if the elements specified by selector or wait_for options are not found on the page after waiting for wait_timeout.


fail_if_selector_present

default: false

Fails the request if the element specified by wait_to_leave option is found on the page after waiting for wait_timeout.


fail_on_4xx

default: false

If fail_on_4xx=true and the requested URL returns a status code >= 400 and <= 499, Urlbox will fail the request with error code 400 and the message: Failed to render. Requested URL returned a 4xx error code and fail_on_4xx was true


fail_on_5xx

default: false

If fail_on_5xx=true and the requested URL returns a status code >= 500 and <= 599, Urlbox will fail the request with error code 400 and message: Failed to render. Requested URL returned a 5xx error code and fail_on_5xx was true

Was this page helpful?