Shotbot Glossary
Definitions of key terms for the Shotbot screenshot API, grouped by theme. Click any term to get a direct anchor link. Something missing? Let us know.
Screenshots
A visual snapshot of a web page as it appears in a browser at a given moment. Shotbot generates screenshots using a headless Chromium browser that runs JavaScript, loads all resources, and waits for the page to stabilize before capturing the image.
A 1280 px wide WebP thumbnail generated automatically for every APIv2 capture. It is displayed on the result page /s/{token} and accessible at cache.shotbot.net/t/{token}/preview.
A screenshot of the entire page height, well beyond the visible viewport area. Enabled with full_page=true in the APIv2 request. Useful for long pages where you need to capture all the content in a single image.
A screenshot that is not uploaded to the public CDN. The file is downloaded via GET /capture/{token}/file (fetchable any number of times) and is automatically purged after a short retention window. Enabled with private=true; it is the default over the CLI and MCP. Deduplication is disabled in private mode.
The process by which the headless browser loads and displays a web page before generating the image. The actual rendering duration, from navigation to capture, is measured in seconds and stored in the render_time_s field.
Formats & dimensions
The simulated browser window dimensions (width × height in pixels). Determines how the page is laid out before capture. The default width is 1280 px. Shotbot Pro subscribers can use custom viewports from 280 to 3840 px wide.
The final width of the generated image, independent of the viewport. The page is first rendered at viewport width, then the image is resized to the requested output size. Controlled by the output_size parameter in APIv2.
The width-to-height ratio applied to crop the image after rendering. The default ratio is 16:9. Shotbot Pro subscribers can set an exact height in pixels via crop_height to produce custom formats.
The file type produced by Shotbot. Five formats are available: JPEG (compressed, best for photos and visuals), PNG (lossless, best for text and UI), WebP (modern, smaller than JPEG at equal quality), AVIF (next-generation, maximum compression), PDF (printable document).
The compression level applied to the generated image (JPEG, WebP, AVIF). Expressed from 1 to 100: a high value preserves detail but produces a larger file. Default quality: 95 (JPEG), 92 (WebP), 85 (AVIF).
API & integration
The secret credential that authenticates your requests to Shotbot. Pass it in the HTTP header Authorization: Bearer {key} for APIv2, or as the k={key} parameter for APIv1. Available from your account page.
A 32-character unique identifier assigned to every APIv2 capture. Used to check progress and retrieve the final image. Base62 format ([A-Za-z0-9]). Example output URL: static.shotbot.net/{t1}/{t2}/{token}.jpg.
The current state of an APIv2 capture. Four possible values: queued (waiting to be processed), processing (in progress), done (completed successfully), failed (error). Polled via GET /capture/{token}.
Captures are processed through dedicated queues depending on their type: paid accounts and credits (Q2), batch jobs (Q3), anonymous web form (Q4). Shotbot Pro subscribers benefit from elevated priority within the Q2 queue.
Bulk submission of multiple URLs in a single API request (POST /capture/batch). The default limit is 500 URLs per request, raised to 5,000 for Shotbot Pro subscribers. Quota is deducted atomically to prevent overruns.
A URL notified via HTTP POST as soon as a capture is complete. Avoids repeated polling of the API. Configured via callback_url and secured with callback_secret: Shotbot includes the secret in the notification, which you verify server-side.
If the same URL is submitted while a capture for it is still queued or processing, Shotbot returns the existing job without creating a duplicate. Deduplication is disabled in private mode and when a forced refresh is requested.
Advanced options
A delay, in seconds, given to the page's JavaScript before the screenshot is triggered. Useful for single-page applications (SPAs), animations, or asynchronous content loading. Range: 0-5 s (up to 30 s for Shotbot Pro). Parameter: wait_time.
A CSS expression targeting a specific element on the page. The screenshot is automatically cropped to that element's bounding box. Useful for isolating a chart, a component, or a section of a page. Shotbot Pro only. Parameter: selector.
Emulates the system preference prefers-color-scheme: values are dark or light. Lets you capture a site's dark mode without modifying the URL or injecting CSS. Available for all accounts. Parameter: color_scheme.
A decorative overlay composited around the captured image. Available variants: drop shadow (shadow), browser chrome (browser_chrome, showing the real URL), smartphone mockup (mobile), tablet mockup (tablet), rounded corners (rounded). Free accounts receive a Shotbot watermark on non-empty frames.
The geographic location of the rendering server used: Paris (France), Montreal (Canada), Singapore, Sydney (Australia) or Hanoi (Vietnam). Useful for testing geo-specific content or bypassing regional restrictions. Available for Shotbot Pro subscribers (Paris is free for all). Parameter: render_region.
HTTP Basic Auth credentials passed to the headless browser before the page loads. Allows capturing sites protected by .htaccess or similar mechanisms. Credentials are deleted from the database as soon as the capture completes, or automatically after 2 hours. Parameter: http_auth.
An array of cookies passed to the headless browser before it navigates to the target URL. Allows capturing pages that require an active user session. Maximum 50 cookies per request. Shotbot Pro only. Parameter: cookies.
Account & subscription
The account unit consumed by each generated screenshot. One credit equals one capture, regardless of its size or format. Credits never expire and can be topped up at any time from your account dashboard.
The maximum number of captures available per month, included with paid plans. Automatically reset on the first of each month. Works alongside your credit balance: credits and monthly quota are consumed together.
A monthly subscription unlocking rendering options (CSS selector, cookie injection, render regions, extended wait time up to 30 s), custom viewports up to 3840 px, a priority queue, and a monthly quota of 5,000 captures.
A recurring capture configured to run automatically on a defined schedule: every hour, every day, every week… Managed from the Scheduled captures section of your account. Each run consumes one credit or is charged against your monthly quota.
No term matches. Suggest one.
A term is missing?
The glossary grows over time. If a concept is not defined here, contact us and we will add it.