Skip to main content

Official Python client for the Ulrbox API

Project description


Urlbox Python Library

codecov Tests Linter

The Urlbox Python library provides easy access to the Urlbox website screenshot API from your Python application.

Now there's no need to muck around with http clients, etc...

Just initialise the UrlboxClient and make a screenshot of a URL in seconds.


See the Urlbox API Docs.


Python 3.x


pip install urlbox


First, grab your Urlbox API key* found in your Urlbox Dashboard, to initialise the UrlboxClient instance.

* and grab your API secret - if you want to make authenticated requests. Requests will be automatically authenticated when you supply YOUR_API_SECRET. So you really should.

Quick Start: Generate a Screenshot URL

For use directly in HTML templates, the browser etc.

In your

from urlbox import UrlboxClient

# Initialise the UrlboxClient (YOUR_API_SECRET is optional but recommended)
urlbox_client = UrlboxClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")

screenshot_url = urlbox_client.generate_url({"url": ""})

In your html template:

<img src="{{  screenshot_url }}"/>

Quick Start: Quickly Get a Screenshot of a URL

from urlbox import UrlboxClient

# Initialise the UrlboxClient (YOUR_API_SECRET is optional but recommended)
urlbox_client = UrlboxClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")

# Make a request to the UrlBox API
response = urlbox_client.get({"url": ""})

response.content # Your screenshot 🎉 as binary image data

# save screenshot image to screenshot.png:
with open("screenshot.png", "wb") as f:

All UrlboxClient methods require at least one argument: a dictionary that must include either a "url", or "html" entry, which the Urlbox API will render as a screenshot.

Additional options in the dictionary include:

"format" can be either: png, jpg or jpeg, avif, webp ,pdf, svg, html (defaults to png if not provided).

"full_page", "width", and many more. See all available options here:


{"url": "", "full_page": True, "width": 300}

A More Extensive Get Request

from urlbox import UrlboxClient

urlbox_client = UrlboxClient(api_key="YOUR_API_KEY", api_secret="YOUR_API_SECRET")

options = {
	"url": "",
	"format": "jpg",
	"full_page": False,
	"hide_cookie_banners": True,
	"block_ads": True

response = urlbox_client.get(options)

# The Urlbox API will return binary data as the response with the
# Content-Type header set to the relevant mime-type for the format requested.
# For example, if you requested jpg format, the Content-Type will be image/jpeg
# and response body will be the actual jpg binary data.

response.content # Your screenshot. Which looks like 👇


Other Methods/Requests

The UrlboxClient has the following public methods:


(as detailed in the above examples) Makes a GET request to the Urlbox API to create a screenshot for the url or html passed in the options dictionary.

Example request:

response = urlbox_client.get({"url": ""})
response.content # Your screenshot 🎉


Removes a previously created screenshot from the cache.

Example request:

urlbox_client.delete({"url": ""})


If you just want to get the response status/headers without pulling down the full response body.

Example request:

response = urlbox_client.head({"url": ""})


Example response headers:

   "Date":"Fri, 26 Nov 2021 16:22:56 GMT",
   "Cache-Control":"public, max-age=2592000",
   "Expires":"Sun, 26 Dec 2021 16:16:09 GMT",
   "Last-Modified":"Fri, 26 Nov 2021 16:14:56 GMT",
   "X-Renders-Reset":"Sun Dec 05 2021 09:58:00 GMT+0000 (Coordinated Universal Time)",

You can use these headers to check how many renders you have used or your current rate limiting status, etc.


Uses Urlbox's webhook functionality to initialise a render of a screenshot. You will need to provide a "webhook_url" entry in the options which Urlbox will post back to when the rendering of the screenshot is complete.

Example request:{"url": "", "webhook_url": ""})

Give it a couple of seconds, and you should receive, posted to the webhook_url specified in your request above, a post request with a JSON body similar to:

  "event": "render.succeeded",
  "renderId": "2cf5ffe2-7736-4d41-8c30-f13e16d35248",
  "result": {
    "renderUrl": ""
  "meta": {
    "startTime": "2021-11-25T16:32:32.453Z",
    "endTime": "2021-11-25T16:32:38.719Z"

You can then parse the renderUrl value to access the your screenshot.

Secure Webhook Posts

The Urlbox API post to your webhook endpoint will include a header that you can use to ensure this is a genuine request from the Urlbox API, and not a malicious actor.

Using your http client of choice, access the x-urlbox-signature header. Its value will be something similar to:


Use the webhook_validator helper function that is included, for no extra charge, in the urlbox package to verify that the webhook post is indeed a genuine request from the Urlbox API. Like so:

from urlbox import webhook_validator

# extracted from the x-urlbox-signature header
header_signature = "t=1637857959,sha256=1d721f..."

# the raw JSON payload from the webhook request body
payload = {
	"event": "render.succeeded",
	"renderId": "794383cd-b09e-4aef-a12b-fadf8aad9d63",
	"result": {
		"renderUrl": ""
	"meta": {
		"startTime": "2021-11-24T16:49:48.307Z",
		"endTime": "2021-11-24T16:49:53.659Z",

# Your webhook secret - coming soon.
# NB: This is NOT your api_secret, that's different.
webhook_secret = "YOUR_WEBHOOK_SECRET"

# This will either return true (if the signature is genuinely from Urlbox)
#   or it will raise a InvalidHeaderSignatureError (if the signature is not from Urlbox), payload, webhook_secret)


Feel free to contact us if you spot a bug or have any suggestions at: support[at]

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

urlbox-1.0.6.tar.gz (13.0 kB view hashes)

Uploaded Source

Built Distribution

urlbox-1.0.6-py3-none-any.whl (12.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page