Options Reference

Basic Options

url

The URL of the website you want to screenshot

Examples
url=bbc.co.uk

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/59148a4e454a2c7051488defdb8b246bdea61ace/png?url=bbc.co.uk

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

Open in new tab
url=apple.com

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d61624d9b0e0a4ba3cadf90805806c38a6e4518a/png?url=apple.com

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

Open in new tab
url=google.com

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/5ee277f206869517d00cf1951f30d48ef9c64bfe/png?url=google.com

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

Open in new tab

width

default: 1280

The viewport width of the browser, in pixels

Examples
width=320

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d27da41701ce087265edabe296bf7d0b65a2084c/png?url=apple.com&width=320

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

Open in new tab
width=768

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/a717eb74fdbcecdb6459d42af6a923e3e0d752d1/png?url=apple.com&width=768

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

Open in new tab
width=1280

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/e1761fa8a549ad7fc56183c0ef65922450c6fb9c/png?url=apple.com&width=1280

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

Open in new tab

height

default: 1024

The viewport height of the browser, in pixels

Examples
height=400

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/6edb15cd3b3a80b1cd3fbd3b46661bc1632e7d8a/png?url=apple.com&height=400

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

Open in new tab
height=800

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/9d953dccf0c2cfdbce107f6c53ff8827d8c40f25/png?url=apple.com&height=800

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

Open in new tab
height=1400

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d10c17a92fc129568b52b6e3c615be6a6085aca5/png?url=apple.com&height=1400

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

Open in new tab

full_page

default: false

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

Example
full_page=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/75b3076e5292ccd5cdb98a9c06e78bd92b4e2f31/png?url=urlbox.io&full_page=true

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

Open in new tab

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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4c668f0b94ff2d0a51370a276ae71ed75587586f/png?url=urlbox.io&selector=%23trynow

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

Open in new tab

gpu

default: false

Enable GPU acceleration to render 3D scenes and heavy WebGL content. This is a beta feature and requires pre-approval. Please contact support to enable this feature on your account

Blocking Options

Options for blocking or dismissing certain page elements, such as cookie banners

block_ads

Blocks requests from popular advertising networks from loading

Examples
block_ads=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/fa9abef354bc1c00d5a454aef085b2f12fad4e65/png?url=nytimes.com&block_ads=true

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

Open in new tab
block_ads=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/7c47de5a9d8ebea85dcfe018c4474d9591ec4be3/png?url=nytimes.com

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

Open in new tab

block_urls

Block requests from specific urls from loading

Examples
block_urls=api.urlbox.io

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/ecb438e54bc2ebb504a444da49fb1818fd537a9d/png?url=urlbox.io&block_urls=api.urlbox.io

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","block_urls":"api.urlbox.io"}'

Result

Open in new tab
Blocking multiple domains and using wildcard

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d477bee088d20393df10c16c0a8bb7eada5a3519/png?url=nytimes.com&block_urls=%2Afacebook%2A&block_urls=%2Afullstory%2A&block_urls=%2Acrisp%2A&block_urls=%2Aintercom%2A&block_urls=%2Agetdrip%2A&block_urls=%2Aolark%2A&block_urls=%2Aoptimizely.com%2A&block_urls=https%3A%2F%2Fshift.com%2Fimages%2F%2A&block_urls=%2Asegment.com%2A&block_urls=%2A.optimizely.com&block_urls=everesttech.net&block_urls=userzoom.com&block_urls=doubleclick.net&block_urls=googleadservices.com&block_urls=adservice.google.com%2F%2A&block_urls=connect.facebook.com&block_urls=connect.facebook.net&block_urls=sp.analytics.yahoo.com

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_urls":["*facebook*","*fullstory*","*crisp*","*intercom*","*getdrip*","*olark*","*optimizely.com*","https://shift.com/images/*","*segment.com*","*.optimizely.com","everesttech.net","userzoom.com","doubleclick.net","googleadservices.com","adservice.google.com/*","connect.facebook.com","connect.facebook.net","sp.analytics.yahoo.com"]}'

Result

Open in new tab

Automatically hides cookie banners from most websites

Examples
hide_cookie_banners=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/eb7e742c61d49276028509362a59c695a7d83ce7/png?url=bbc.co.uk&hide_cookie_banners=true

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

Open in new tab
hide_cookie_banners=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/59148a4e454a2c7051488defdb8b246bdea61ace/png?url=bbc.co.uk

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

Open in new tab

click_accept

Automatically clicks 'Accept' buttons, in order to dismiss popups

Examples
click_accept=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/6289a7440552e67d274febda3636f51c39e2ffa4/png?url=bbc.co.uk&click_accept=true

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

Open in new tab
click_accept=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/59148a4e454a2c7051488defdb8b246bdea61ace/png?url=bbc.co.uk

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

Open in new tab

hide_selector

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

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

dark_mode

default: false

Emulate dark mode on websites by setting prefers-color-scheme: dark

Examples
dark_mode=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/9b29671653b8187f14deb76bbd1e0d139123a13b/png?url=https%3A%2F%2Fdark-mode-baseline.glitch.me%2F&dark_mode=true

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://dark-mode-baseline.glitch.me/","dark_mode":true}'

Result

Open in new tab
dark_mode=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/709087f3836a65fdd83f9d8e569a2ae3a6d9b736/png?url=https%3A%2F%2Fdark-mode-baseline.glitch.me%2F

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://dark-mode-baseline.glitch.me/","dark_mode":false}'

Result

Open in new tab

reduced_motion

Prefer less animations on websites by setting prefers-reduced-motion: reduced

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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/1140e4933928b75bbee948ab103b7e88a643e0ec/png?url=urlbox.io&retina=true

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

Open in new tab
retina=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/665935172c589287eb09fbc0cffa78208939941f/png?url=urlbox.io

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

Open in new tab

thumb_width

The width of the generated thumbnail, in pixels. Omit for a full-size screenshot.

Examples
thumb_width=100

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/f0cc62693ea85d9c5685f4a9a44e827d39d5cbe6/png?url=example.com&thumb_width=100

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

Open in new tab
thumb_width=200

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4fd3b986f19bd418143c9ddeeca264dd32ba2ed7/png?url=example.com&thumb_width=200

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

Open in new tab
thumb_width=400

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/63a49589221624368b28015ded7f8299bddc9689/png?url=example.com&thumb_width=400

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

Open in new tab

thumb_height

The height of the generated thumbnail, in pixels. Omit for a full-size screenshot.

Examples
thumb_height=100

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/c203c638e3e9765b4d778095a79497afc467747d/png?url=example.com&thumb_height=100

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

Open in new tab
thumb_height=200

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4edb67595e217b67dfb0530e3161b29c41ddd3f5/png?url=example.com&thumb_height=200

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

Open in new tab
thumb_height=400

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/df901178af16380553a57f0a096ee2e5da95bbb8/png?url=example.com&thumb_height=400

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

Open in new tab

quality

default: 80

The image quality of the resulting screenshot (JPEG/WebP only)

Examples
quality=40

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/e72170720d6e4a7b98a56b29e1dd8375d4011799/png?url=spotify.com&quality=40

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

Open in new tab
quality=80

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/2c996a1c141db7bfb93b55389ae92632d8ab98a1/png?url=spotify.com&quality=80

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

Open in new tab
quality=100

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/7c6b184b3beadda7f6ccaef93da4238f867b1a10/png?url=spotify.com&quality=100

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

Open in new tab

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 which sets the content-disposition header on the response. E.g. download=myfilename.png This will make the Urlbox link downloadable, and will prompt the user to save the file as myfilename.png

Example
download=apple.png

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/a8240a178fcea7c2473fe8e24b37f304615d416b/png?url=apple.com&download=apple.png

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","download":"apple.png"}'

Result

Open in new tab

PDF Options

Options relating to PDF document generation

pdf_page_size

default: A4

Sets the PDF page size. The available 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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/c089868c669aea2090b1d577c53f1860475e3164/pdf?url=example.com&pdf_page_size=A0

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

Open in new tab
pdf_page_size=A4

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d70c0c52f322d1026912a9476794db90f4641e1e/pdf?url=example.com&pdf_page_size=A4

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

Open in new tab
pdf_page_size=Letter

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/36fe235e092809916b4f2e5699ebc1f3b999d36c/pdf?url=example.com&pdf_page_size=Letter

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

Open in new tab

pdf_page_width

Sets the PDF page width, in pixels

pdf_page_height

Sets the PDF page height, in pixels

pdf_margin

default: None

Sets the margin of the PDF document. The available options are

  • none
  • default
  • minimum.
Examples
pdf_margin=none

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/c218a8130c77103da65620c5c69c97ce67acf434/pdf?url=example.com&pdf_margin=none

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

Open in new tab
pdf_margin=default

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/dabdd091f0abecb6d221dc4d4335886d75ca8ddd/pdf?url=example.com&pdf_margin=default

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

Open in new tab
pdf_margin=minimum

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4d3250a9c5ffbcbd1181d9132736d209f34255ed/pdf?url=example.com&pdf_margin=minimum

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

Open in new tab

pdf_margin_top

Sets a custom top margin on the PDF.

Example
pdf_margin_top=40

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/6554dc261a8485c5602210ac060392fdc0dec9ac/pdf?url=example.com&pdf_margin_top=40

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

Open in new tab

pdf_margin_right

Sets a custom right margin on the PDF.

Example
pdf_margin_right=100

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/08fa46516c2d447ef67bee88d88fcf77d2cb84bd/pdf?url=example.com&pdf_margin_right=100

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

Open in new tab

pdf_margin_bottom

Sets a custom bottom margin on the PDF.

Example
pdf_margin_bottom=50

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/8b22eb20b781cca1d2fbfbb75797b5a75d181d26/pdf?url=example.com&pdf_margin_bottom=50

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

Open in new tab

pdf_margin_left

Set a custom left margin on the PDF.

Example
pdf_margin_left=60

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/99d3dab5829cf0bb04db13861b0edb2a4b481ff0/pdf?url=example.com&pdf_margin_left=60

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

Open in new tab

pdf_scale

default: 1

Sets the scale factor of the website content in the PDF. Valid values are numbers between 0.1 and 2

Examples
pdf_scale=0.2

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/47aff19c88a87eeec9e00f943c68bd94f5f71ba3/pdf?url=example.com&pdf_scale=0.2

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

Open in new tab
pdf_scale=1.2

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/ed6142bc72eaae080e355dcc8b1401e917ee9c93/pdf?url=example.com&pdf_scale=1.2

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

Open in new tab
pdf_scale=2

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/1c6130cae34d07611e12386ea8126e56aba009b1/pdf?url=example.com&pdf_scale=2

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

Open in new tab

pdf_orientation

default: Portrait

Sets the orientation of the PDF. The available options are

  • portrait
  • landscape
Examples
pdf_orientation=portrait

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/0f14e7117d57a6b326cd5dae583946060b6899e8/pdf?url=example.com&pdf_orientation=portrait

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

Open in new tab
pdf_orientation=landscape

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/702e18cf83eb432a9271676ecfbc69ed273e6b28/pdf?url=example.com&pdf_orientation=landscape

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

Open in new tab

pdf_background

default: true

Sets whether to print background images in the PDF

Examples
pdf_background=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/3243ad16a18fbf17329e1e0aee4f9d8de1015110/pdf?url=bbc.com&pdf_background=true

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

Open in new tab
pdf_background=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/277acac44329642f4d79dcda866e39aebd7f677d/pdf?url=bbc.com

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

Open in new tab

disable_ligatures

Prevents 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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/157f8d05a0c7515482b32a901eb12075b0086a42/pdf?url=https%3A%2F%2Fkubla.fi%2Fyhteystiedot%2F&disable_ligatures=true

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

Open in new tab
disable_ligatures=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/464b2892f6bcce9f4e8387bf69437a54a91bd033/pdf?url=https%3A%2F%2Fkubla.fi%2Fyhteystiedot%2F

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

Open in new tab

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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/46da7427ec85077ffb1b296418e0b41226a25209/pdf?url=bbc.co.uk&media=screen

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

Open in new tab
media=print

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/8d92b9f8e0ddb3df8daae7821cc6804d1a7f8355/pdf?url=bbc.co.uk&media=print

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

Open in new tab

Cache Options

Options to control how Urlbox caches your screenshots or PDF's

force

default: false

Generate a fresh screenshot or PDF, instead of getting a cached version.

unique

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=1664658737703.

ttl

default: 2592000 (30 days - this is also the maximum value)

The duration ('time to live') to keep a screenshot or PDF in the cache, in seconds.

Examples
1 day

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/8815ef52c20bfdbf2e80389614a7bec2c370119e/png?url=nytimes.com&ttl=86400

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

Open in new tab
1 week

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/b5b31ce180137db2e9cd0e850ddc3fdc443b90f3/png?url=nytimes.com&ttl=604800

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

Open in new tab
1 month

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/147bd49d8a6297f79d163469ed0425c4cfff26a6/png?url=nytimes.com&ttl=2592000

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

Open in new tab

Request Options

Options to configure the browser, before navigating to the URL

proxy

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

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

Set a header on the request when loading the URL

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

This 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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/f21af044899d3f6185e2f5c831f642927f3ed13e/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-http-headers-is-my-browser-sending&full_page=true&block_ads=true&header=X-My-Header%3DMyHeaderValue

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

Open in new tab
Setting multiple headers

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/dee4f57fde5b233c351a163ed7617512b75783fd/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-http-headers-is-my-browser-sending&full_page=true&block_ads=true&header=X-Header-1%3DvalueOfHeader1&header=X-Header-2%3DvalueOfHeader2

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

Open in new tab

Sets a cookie on the request when loading the URL

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

This 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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/442e329408abc1302b9ac42fad8764f5fdbc6319/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-http-headers-is-my-browser-sending&full_page=true&block_ads=true&cookie=OptIn%3Dyes

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

Open in new tab
Setting multiple cookies

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/1612225ce23701bc66a7588a913926513de6d7d6/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-http-headers-is-my-browser-sending&full_page=true&block_ads=true&cookie=OptIn%3Dyes&cookie=BestScreenshots%3Durlbox

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

Open in new tab

user_agent

Sets 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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/ad5bcdf6a9071129d6b19318e03422d3a79f1ab9/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-is-my-user-agent&block_ads=true&user_agent=random

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

Open in new tab
user_agent=mobile

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d93ca172911defd7cd86c9c3b3784d93b7de5c74/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-is-my-user-agent&block_ads=true&user_agent=mobile

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

Open in new tab
user_agent=desktop

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/ac9ac53a8574ac1bdb64e3bea751c1540e5d2422/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-is-my-user-agent&block_ads=true&user_agent=desktop

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

Open in new tab
Google bot

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/13950a1db702e099a8053e9784247d4b77d958fe/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-is-my-user-agent&block_ads=true&user_agent=Googlebot%2F2.1%20%28%2Bhttp%3A%2F%2Fwww.google.com%2Fbot.html%29

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

Open in new tab
Facebook crawler

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/810f8882103ba1684f1f99eaca296cdb89ab7b17/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-is-my-user-agent&block_ads=true&user_agent=facebookexternalhit%2F1.1

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

Open in new tab
Custom

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/8da4b2ed2f8b7317e9e2c000add31e9b6935170a/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-is-my-user-agent&block_ads=true&user_agent=Mozilla%2F5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X%2011_2_3%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F89.0.4389.90%20Safari%2F537.36

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

Open in new tab

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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/90a819ac70c4413c818d6c7f49d72cd7098a77c9/png?url=microsoft.com&accept_lang=de-CH

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

Open in new tab
accept_lang=ko-KR

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4039f4ab80731306bf7afc9a652536a9b63c42bc/png?url=microsoft.com&accept_lang=ko-KR

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

Open in new tab

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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/745f5ea83e82ecbcf78cc09f204844339af96bf7/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-http-headers-is-my-browser-sending&full_page=true&block_ads=true&authorization=Basic%20my_base64_auth_token

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

Open in new tab
authorization=Bearer my_bearer_token

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/7392baab4350e6e3302d20c9b953130b8aee7dab/png?url=https%3A%2F%2Fwww.whatismybrowser.com%2Fdetect%2Fwhat-http-headers-is-my-browser-sending&full_page=true&block_ads=true&authorization=Bearer%20my_bearer_token

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

Open in new tab

tz

default: UTC

Sets the local timezone to use for the screenshot

Example: tz=Europe/London

Examples
tz=Europe/London

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/0c5666fcf2fd899868be3f1a4435b787a2667747/png?url=https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dwhat%2Bis%2Bmy%2Btimezone&tz=Europe%2FLondon

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

Open in new tab
tz=America/New_York

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/637f052f3a1be9189fb34a8e107561e31a7ee56a/png?url=https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dwhat%2Bis%2Bmy%2Btimezone&tz=America%2FNew_York

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

Open in new tab

Wait Options

delay

default: 0

The amount of time to wait before Urlbox takes the screenshot or PDF, in milliseconds.

timeout

default: ``30000 (30 seconds)

The amount of time to wait for the requested URL to respond, in milliseconds.

wait_until

Waits until the specified DOM event has fired before taking a screenshot or PDF

The available options are:

  • domloaded (the DOMContentLoaded event is fired)
  • mostrequestsfinished (consider navigation to be finished when there are no more than 2 network connections for at least 500 ms)
  • requestsfinished (there are no more than 0 network connections for at least 500 ms)
  • loaded (the load event is fired)
Examples
wait_until=domloaded

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/82aaf1df38e74245b8d0c68f637f42e1f8373a39/png?url=example.com&wait_until=domloaded

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

Open in new tab
wait_until=mostrequestsfinished

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/4ae28194c1c8f1d5e8cb9935d0db53a18eee06a1/png?url=example.com&wait_until=mostrequestsfinished

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

Open in new tab
wait_until=requestsfinished

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/e306da31335b4c3b349a980adc15532f4948056b/png?url=example.com&wait_until=requestsfinished

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

Open in new tab
wait_until=loaded

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/cc08f1746b0f5683d2130835fe8aaef1014958d5/png?url=example.com&wait_until=loaded

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

Open in new tab

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

Examples
Without wait_for

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/3f97530c0376dddd06b5fab77c743f0eb7ca7bc0/png?url=test-site.urlbox.io%2Floads_in%2F10%2Fseconds

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":"test-site.urlbox.io/loads_in/10/seconds"}'

Result

Open in new tab
wait_for=#loaded_element

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/8ba6c5bce0580470b70a3afe8e4292e5c0f1c1ec/png?url=test-site.urlbox.io%2Floads_in%2F10%2Fseconds&wait_for=%23loaded_element

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":"test-site.urlbox.io/loads_in/10/seconds","wait_for":"#loaded_element"}'

Result

Open in new tab

wait_to_leave

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

A typical use-case would be waiting for loading spinners to be absent 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

Examples
Without wait_to_leave

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/3f97530c0376dddd06b5fab77c743f0eb7ca7bc0/png?url=test-site.urlbox.io%2Floads_in%2F10%2Fseconds

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":"test-site.urlbox.io/loads_in/10/seconds"}'

Result

Open in new tab
wait_to_leave=#loading_element

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d496a3b45d66cae433d5cbfba4576cec0e953fc5/png?url=test-site.urlbox.io%2Floads_in%2F10%2Fseconds&wait_to_leave=%23loading_element

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":"test-site.urlbox.io/loads_in/10/seconds","wait_to_leave":"#loading_element"}'

Result

Open in new tab

wait_timeout

default: ``30000 (30 seconds)

The amount of time to wait for the wait_for element to be available before continuing, in milliseconds

Page Options

Options to modify the page state before taking a screenshot or PDF

scroll_to

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

Examples
scroll_to=#trynow

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/b5d8d7fccf5822ea956f60584870f21686c07d88/png?url=urlbox.io&scroll_to=%23trynow

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

Open in new tab
scroll_to=1024

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/f4058a258a7bdb421145ffd5651aab5d2937c813/png?url=urlbox.io&scroll_to=1024

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

Open in new tab
scroll_to=5000

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/6ad6a56bfb9a4540895f19987016283ff712a380/png?url=urlbox.io&scroll_to=5000

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

Open in new tab

click

Specifies an element selector to click before generating a screenshot or PDF

Example: #clickme would click an 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

Specifies an element selector to click before generating a screenshot or PDF

Example: .clickme would click all elements with class="clickme".

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

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

hover

Specifies an element selector to hover over before generating a screenshot or PDF

Example: #hoverme would hover over the element with id="hoverme"

bg_color

Specified a hex code or CSS color string to use as the background color

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 the target URL.

Examples
disable_js=true

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/d468bc7f9b2ef426cdc23770fa472fab9b13ab61/png?url=nytimes.com&disable_js=true

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

Open in new tab
disable_js=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/7c47de5a9d8ebea85dcfe018c4474d9591ec4be3/png?url=nytimes.com

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

Open in new tab

Full Page Options

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

full_width

default: false

When full_page=true, specify whether to capture the full width of the website, for example if the site is horizontally scrolling.

allow_infinite

By default, when Urlbox detects an infinite scrolling page, it does not attempt to continue scrolling to 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:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/9b4e567bf2f9cffe5f2f09c4285ff7f027f2e0f7/png?url=urlbox.io&full_page=true&skip_scroll=true

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

Open in new tab
skip_scroll=false

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/75b3076e5292ccd5cdb98a9c06e78bd92b4e2f31/png?url=urlbox.io&full_page=true

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

Open in new tab

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 to 4096 pixels. If a sites height is greater than this value, Urlbox will start splitting the screenshot into sections. Sometimes it is worthwhile experimenting with this number.

scroll_increment

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

scroll_delay

When Urlbox decides to split a screenshot into multiple sections, the scroll delay is the time to wait between taking the screenshots of each individual section, in milliseconds. While 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 This is an experimental option. Used to speed up full page screenshots, but at the expense of accuracy.

Highlighting Options

Options for highlighting a given string on the page

highlight

Specified a string to highlight on the page before capturing a screenshot or PDF

highlightfg

default: white

Specified the text color of the highlighted word

highlightbg

default: red

Specified the background color of the highlighted word

Geolocation Options

Options for the geolocation API

latitude

Sets the latitude used to emulate the Geolocation API

Example
latitude=74.006

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/b34b779559fcea81e39a0d8bf04201405a7a6514/png?url=https%3A%2F%2Fwww.infobyip.com%2Fbrowsergeolocation.php&longitude=40.7128&latitude=74.006

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

Open in new tab

longitude

Sets the longitude used to emulate the Geolocation API

Example
longitude=40.7128

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/f202972ec1c027e8d5ad555b73b910ce4f2e2417/png?url=https%3A%2F%2Fwww.infobyip.com%2Fbrowsergeolocation.php&latitude=74.006&longitude=40.7128

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

Open in new tab

accuracy

Sets the accurate of the Geolocation API, in metres

Examples
accuracy=100

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/cc71c05bdd819f87a98f8aa04b8f3f14d2551b7a/png?url=https%3A%2F%2Fwww.infobyip.com%2Fbrowsergeolocation.php&latitude=74.006&longitude=40.7128&accuracy=100

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

Open in new tab
accuracy=5000

Example Urlbox GET request:

https://api.urlbox.io/v1/ca482d7e-9417-4569-90fe-80f7c5e1c781/c935bc46e918222dab91df6f24c724d909d9e041/png?url=https%3A%2F%2Fwww.infobyip.com%2Fbrowsergeolocation.php&latitude=74.006&longitude=40.7128&accuracy=5000

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

Open in new tab

Storage Options

Options related to storing the screenshots in Amazon S3

use_s3

default: false

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

s3_path

Sets the S3 path, including subdirectories and the filename, to use when saving the screenshot in your S3 bucket.

s3_bucket

Overrides the configured S3 bucket to use when saving the screenshot.

s3_storageclass

default: standard

Sets the s3 storage class.

The available options are:

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

Request Behaviour Options

Options to 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 between 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 between 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

PreviousWebhooks | IntroductionNextExample Code | Node.js
Was this page helpful?