How to Capture a Website Screenshot Using URLbox

To capture a website screenshot with URLbox, create a render link with your API key, an output format, and the target URL. Open the link to render the image, or use URLbox’s JSON API or CLI to save and process screenshots in an application or terminal. For production, sign render links or use Bearer authentication with the JSON API, and keep your secret key on the server.

This guide is in English and covers the URLbox workflow, including mobile viewport settings, full-page captures, element captures, authentication, code examples, troubleshooting, and file retention.

1. Get your URLbox credentials

Get an API key and secret key from the URLbox Quick Start. The API key appears in render links. The secret key is used to sign secure links or authenticate JSON API requests. Keep the secret key out of browser code, public repositories, and client-side applications.

2. Make a basic screenshot render link

The basic render link puts the API key and format in the path and the target page in the query string:

https://api.urlbox.com/v1/YOUR_API_KEY/png?url=https%3A%2F%2Fexample.com

Replace YOUR_API_KEY with your API key. The png path segment selects PNG output, and url specifies the page to capture. URL-encode the target URL, especially if it contains its own query parameters. Open the link in a browser to view the rendered image or fetch it from a program.

For example, add width and height to set the viewport. A 390 by 844 viewport approximates a common mobile layout:

https://api.urlbox.com/v1/YOUR_API_KEY/png?url=https%3A%2F%2Fexample.com&width=390&height=844

URLbox documents render options such as format, viewport dimensions, and thumbnail width in its Quick Start and documentation. Use the options reference to check supported values for the settings your capture needs.

3. Capture a full page or one element

Full-page screenshot

Set full_page=true to capture beyond the initial viewport:

https://api.urlbox.com/v1/YOUR_API_KEY/png?url=https%3A%2F%2Fexample.com&full_page=true

URLbox’s default full-page stitch mode scrolls the page to trigger lazy-loaded elements and work out the page height before capturing and stitching sections. The documentation also describes a native full-page mode that can be faster but may be less reliable on some pages. If a page has sticky headers, animations, or content that changes as you scroll, check the resulting image carefully and try the default stitch behavior if native capture misses content.

Capture a specific element

Use the selector option with a CSS selector when you need a component such as a chart, product card, or article body instead of the whole viewport. Find a stable selector in Chrome DevTools, then pass it as an encoded query parameter. For example:

https://api.urlbox.com/v1/YOUR_API_KEY/png?url=https%3A%2F%2Fexample.com&selector=%23main-content

Here, %23main-content is the encoded form of #main-content. Prefer selectors tied to stable IDs or classes over selectors based on page position. If the selector is missing on some pages, handle that as a capture failure in your application instead of assuming the screenshot contains the desired element.

4. Use the JSON API from code

URLbox also supports synchronous and asynchronous rendering through its JSON REST API. The synchronous endpoint accepts render options as JSON and uses the secret key as a Bearer token. Its response includes a renderUrl and render metadata. According to the Quick Start, the example render URL expires after 30 days; download the image or configure cloud bucket storage if you need to retain it.

cURL

curl --fail --silent --show-error \
  -X POST "https://api.urlbox.com/v1/render/sync" \
  -H "Authorization: Bearer YOUR_URLBOX_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","width":390,"height":844,"format":"png"}'

The JSON response contains a temporary render URL. Fetch that URL to save the image:

curl --fail --location "RENDER_URL_FROM_JSON_RESPONSE" --output screenshot.png

Python

import requests

secret = "YOUR_URLBOX_SECRET"
payload = {
    "url": "https://example.com",
    "width": 390,
    "height": 844,
    "format": "png",
}

response = requests.post(
    "https://api.urlbox.com/v1/render/sync",
    headers={"Authorization": f"Bearer {secret}"},
    json=payload,
    timeout=120,
)
response.raise_for_status()
render_url = response.json()["renderUrl"]

image = requests.get(render_url, timeout=120)
image.raise_for_status()
with open("screenshot.png", "wb") as output:
    output.write(image.content)

Node.js

const secret = process.env.URLBOX_API_SECRET;
if (!secret) throw new Error('Set URLBOX_API_SECRET before running this script');

const response = await fetch('https://api.urlbox.com/v1/render/sync', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${secret}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    width: 390,
    height: 844,
    format: 'png',
  }),
});
if (!response.ok) throw new Error(`URLbox request failed: ${response.status}`);
const { renderUrl } = await response.json();

const image = await fetch(renderUrl);
if (!image.ok) throw new Error(`Image download failed: ${image.status}`);
await import('node:fs/promises').then(({ writeFile }) =>
  writeFile('screenshot.png', Buffer.from(await image.arrayBuffer()))
);

Save the Node.js example in a file that runs as an ES module. Set URLBOX_API_SECRET in the environment before running it. In production, also set timeouts and retry behavior appropriate to your job queue, and avoid logging credentials.

5. Secure render links

A render link that exposes only an API key is convenient for experiments and controlled use. For production links that users can modify, URLbox documents signing the query-string options with an HMAC-SHA256 token made from the secret key. The token is included in the URL path. If someone changes signed options, the signature no longer matches and the request is rejected. Generate signatures on a trusted server and keep the secret private. The Quick Start shows the signing format and an example.

Use the JSON API when you want server-side authentication, a structured response, or synchronous and asynchronous rendering. Use a render link when a direct image URL fits your use case, such as embedding a generated image. Do not put a secret key in a public webpage or mobile app.

6. Save a screenshot with the URLbox CLI

The CLI is useful for local work, scripts, and CI. Install it and authenticate, then capture a full page:

npm install -g @urlbox/cli
urlbox login
urlbox screenshot https://example.com --full-page --output page.png

In CI, the CLI quickstart documents using URLBOX_API_SECRET for authentication. You can validate a command without rendering by adding --dry-run:

urlbox screenshot https://example.com --full-page --dry-run

The CLI also accepts API options through --json; see the CLI Quickstart for examples and the complete option reference.

7. Choose settings for the page you need

Need	Setting or approach	Check
Mobile layout	Set width and height to the target viewport.	Confirm the page responds to that viewport; dimensions do not guarantee a specific physical device.
Entire scrolling page	Set full_page=true.	Review lazy-loaded content, sticky elements, and long-page stitching.
One component	Set selector to a CSS selector.	Confirm the selector exists and uniquely identifies the intended element.
Smaller thumbnail	Use thumb_width where appropriate.	Verify the output dimensions and legibility at the resized width.
Application integration	Use the JSON API.	Handle the response and temporary URL; download or store output you need to retain.
Shell workflow	Use the CLI screenshot command.	Use --dry-run to validate the command before rendering.

These examples cover the relevant settings in this workflow; consult the URLbox documentation for the full current render-options list and details. A screenshot records a page at a particular moment. Pages with personalization, geolocation, authentication, delayed content, or animation can render differently across requests, so control those inputs when repeatability matters.

8. Troubleshoot common problems

Symptom	Likely cause	What to do
Authentication or signature error	The API key or secret is wrong, the token was generated from different options, or signed options changed after signing.	Check the credential type for the chosen method. Recreate the HMAC from the exact query options and keep the secret server-side.
Invalid or malformed target URL	The URL is missing its scheme or query characters were not encoded correctly.	Use a complete URL such as https://example.com and encode the target URL when building a render link.
Screenshot is blank or incomplete	The page may need more time, rely on lazy loading, or render content after scrolling.	Try full-page stitch mode, verify the target is publicly reachable, and consult the render-options documentation for supported wait settings.
Element capture returns the wrong area or fails	The selector may not exist, may match multiple elements, or may depend on a transient class.	Inspect the page in DevTools, use a stable selector, and verify it on the exact URL and viewport being rendered.
Full-page capture is missing sections	Some content may load only after scrolling, or a faster native mode may not suit the page.	Use the default stitch mode and inspect pages with sticky headers, lazy-loaded sections, or changing content.
Saved image link stops working later	The JSON API’s example render URL is temporary and expires after 30 days.	Download the file promptly or configure cloud bucket storage for longer retention.
CLI command fails before rendering	The CLI may not be installed, authenticated, or configured in the current environment.	Run urlbox doctor, check authentication, and use --dry-run to validate the request. See the CLI guide.

9. Performance, reliability, and cost considerations

• Page complexity matters: Full-page captures and pages with lazy-loaded or delayed content can require more work than a viewport capture. Choose the smallest capture scope that meets your need.
• Use async rendering for queued work: URLbox documents both synchronous and asynchronous JSON rendering. Async rendering is an option for workloads that should be queued rather than held open in a request path.
• Design for temporary outputs: Treat the JSON API’s render URL as temporary. Download and persist the image when your application needs durable access.
• Handle failures explicitly: Check HTTP status codes, set client timeouts, and record enough request context to reproduce a failed capture without logging secrets.
• Check current plan terms: The dossier does not establish durable pricing or an independently verified cost comparison. Review URLbox’s current account and plan details before estimating production spend. The Quick Start’s stated seven-day trial is a vendor offer and may change.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF, and the same request can be made from cURL, Python, or Node.js. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

• Cookie banners, popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; response headers identify the page verdict and billing result.
• An MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs.
• 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots.

Create a free ScreenshotNeo account to get 1,000 screenshots a month with no card.

FAQ

Can I use a render link directly in an image tag?

Render links return an image directly, which can suit an image tag. For public use, secure the link as appropriate and avoid exposing your secret key.

Can I capture a URL that requires a login?

A screenshot service must be able to access the page and its content. Review URLbox’s current options and documentation for authenticated-page workflows before relying on a capture of a private page.

Does a screenshot render URL last forever?

No. URLbox’s Quick Start says the example JSON API render URL expires after 30 days. Download the image or configure bucket storage if you need to keep it.

Which method should I start with?

Use a render link to understand the basic request, the JSON API for application integration, and the CLI for terminal or CI workflows.