The web capture glossary: 63 screenshot terms, A to Z
Every term you meet when you capture a web page, defined in one or two sentences, checked against a primary source, and linked to the terms it depends on.
63 terms
All 63 terms, A to Z
Each definition stands on its own, so it can be quoted without the rest of the page. Every entry has an address of its own: the link icon copies it. Where a term matches an option of the CurlShot API, the exact option name is shown.
A3 terms
- Accessibility treeAlso: a11y tree, accessibility snapshot
An accessibility tree is a structure the browser builds from a page that holds accessibility-related information for most HTML elements: the name, description, role and state of each one.[49]
Why it matters for a screenshot. An agent can read the accessibility tree as text to find a button by its name and role, and keep the screenshot for what text cannot say: layout, colour and what is visually broken.
Example
role: button, name: "Read more"Related: Vision model, Tool call, CSS selector
AI and agents · Screenshots for AI agents
- Alpha channelAlso: transparency, opacity, transparent background
An alpha channel is the fourth channel of a colour, next to red, green and blue, and it specifies opacity, so the background can be seen through a pixel to some extent.[27][24]
Why it matters for a screenshot. A screenshot with a transparent background needs a format that has an alpha channel: PNG and WebP have one, JPEG does not.
- Anti-aliasingAlso: antialiasing, font smoothing, subpixel rendering
Anti-aliasing is the smoothing a renderer applies to the edges of text and shapes, on the level of the pixel or of the subpixel.[53][18][17]
Why it matters for a screenshot. Browser rendering varies with the operating system, its settings and the hardware, so comparison libraries such as pixelmatch detect anti-aliased pixels and leave them out of the count by default.
Related: Diff, Threshold, Flaky test
Testing · Visual regression testing guide
B1 term
- BaselineAlso: reference screenshot, snapshot, expected image
A baseline is the approved reference screenshot that later screenshots of the same page are compared against. Playwright generates it on the first run of a test and stores it next to the test file.[17]
Why it matters for a screenshot. A comparison is only as good as its baseline: take the baseline in the same environment that takes the new screenshots, because rendering varies between machines.
Example
npx playwright test --update-snapshotsRelated: Diff, Threshold, Visual regression test
Testing · Visual regression testing guide
C8 terms
- Cache hitAlso: cache miss, HIT, MISS, cached screenshot, fresh render
A cache hit is a request answered with a stored copy of an earlier result. A cache miss is the opposite: no stored copy exists, so the result is produced fresh and can then be stored.[35][36]
Why it matters for a screenshot. A cache hit returns a screenshot without opening the page again, so it is faster and shows the page as it was when the copy was made. In CurlShot the
X-Cacheheader saysHITorMISS, and a hit does not use a screenshot from the quota.Example
X-Cache: HITRelated: Time to live, Quota, Signed URL
Security and limits · Website thumbnail sizes
- CodecAlso: H.264, VP9, AV1, encoder
A codec is a program, algorithm or device that encodes or decodes a data stream, and each codec handles one specific encoding or compression technology.[28][29]
Why it matters for a screenshot. A recording of a scrolling page is compressed by a video codec, and a player must support that codec to show it. CurlShot encodes MP4 with H.264 and WebM with VP9.
Example
H.264, VP9, AV1Related: Container format, Frame rate, Lossy compression
Formats · Website video as MP4, WebM or GIF
- Container formatAlso: container, media container, MP4, WebM, file type
A container format is a file format that encapsulates one or more media streams, such as video and audio, along with metadata, so they can be stored and played back together.[29]
Why it matters for a screenshot. The file extension of a page recording names the container, not the codec: an MP4 file can hold H.264, AV1 or VP9 video, and a WebM file holds VP8, VP9 or AV1.
Example
format=mp4- CSS pixelAlso: px, logical pixel, reference pixel, point
A CSS pixel is the CSS unit of absolute length
px, defined as exactly 1/96 of a CSS inch. A CSS pixel is a unit of layout, not one dot of a screen.[2][3]Why it matters for a screenshot. Viewport sizes and element positions are given in CSS pixels, while a screenshot file is counted in device pixels, so the two numbers differ whenever the device pixel ratio is not 1.
Example
390 CSS px wide at ratio 3 = 1170 px in the fileRelated: Device pixel, Device pixel ratio, Viewport
Layout and pixels · Viewport sizes cheat sheet
- CSS selectorAlso: selector, query selector
A CSS selector is the part of a CSS rule that describes which elements in a document the rule matches.[8]
Why it matters for a screenshot. Capture tools reuse selectors to point at one element: to screenshot only that element, to hide it, to click it, or to wait until it exists.
Example
#pricing, .cookie-bar, div.warningAPI optionselectorhide_selectorswait_for_selectorclick
Related: Element screenshot, Shadow DOM, Iframe
Layout and pixels · CSS selectors for element screenshots
D6 terms
- Dark modeAlso: prefers-color-scheme, colour scheme, color scheme, dark theme
Dark mode is a dark colour scheme that a page offers through the
prefers-color-schememedia feature, which detects whether the user prefers a light or a dark colour scheme.[6][20]Why it matters for a screenshot. A capture browser can emulate the dark preference, so the same address gives a light and a dark screenshot. A page that has no dark styles looks the same in both.
Example
@media (prefers-color-scheme: dark) { ... }API optiondark_mode
Related: Media query, Device emulation, Print media
Automation · Dark mode screenshots
- Device emulationAlso: emulation, device preset, device descriptor, mobile emulation
Device emulation is making a browser simulate a particular phone, tablet or desktop by setting its user agent, screen size, viewport and touch support, without having the device.[20]
Why it matters for a screenshot. Emulation is how one server takes a phone, a tablet and a desktop screenshot of the same address. It simulates the browser of the device, not its hardware.
Example
viewport_device=iphone_15_proAPI optionviewport_deviceviewport_mobile
Related: Viewport, Device pixel ratio, User agent
Automation · Full-page screenshots on every device
- Device pixelAlso: physical pixel, hardware pixel, screen pixel
A device pixel is one physical pixel of a display, and the unit a screenshot file is counted in.[3][16]
Why it matters for a screenshot. The width and height of a screenshot are device pixels: a 1280 CSS pixel wide viewport at a device pixel ratio of 2 gives a file 2560 pixels wide.
Related: CSS pixel, Device pixel ratio, Image size
Layout and pixels · Viewport sizes cheat sheet
- Device pixel ratioAlso: DPR, device scale factor, Retina, HiDPI, 2x, pixel density
A device pixel ratio is the ratio of the resolution of a display in physical pixels to its resolution in CSS pixels: the number of device pixels used to draw one CSS pixel along one side. A value of 1 is a classic 96 DPI display and 2 is expected for HiDPI or Retina displays.[3]
Why it matters for a screenshot. Device pixel ratio multiplies the pixel size of a screenshot and makes text sharper without changing the layout of the page.
Example
1 (classic), 2 (HiDPI), often above 2 on phonesAPI optiondevice_scale_factor
Related: CSS pixel, Device pixel, Image size
Layout and pixels · Viewport sizes cheat sheet
- DiffAlso: image diff, pixel diff, visual diff, comparison
A diff is the comparison of a new screenshot with a baseline, pixel by pixel, that reports which pixels are different and how many there are.[18][17][16]
Why it matters for a screenshot. A diff turns the question of whether a page still looks right into a number a script can check, and it is where a moved button or a missing image shows up.
Example
maxDiffPixels: 100Related: Baseline, Threshold, Anti-aliasing
- DOMContentLoadedAlso: DOM ready, document ready, DOM content loaded
DOMContentLoaded is the browser event that fires when the HTML document has been completely parsed and all deferred scripts have downloaded and executed. DOMContentLoaded does not wait for images, subframes or async scripts.[11][14]
Why it matters for a screenshot. A screenshot taken at DOMContentLoaded can show the text and the layout with empty image boxes, so it suits captures where speed matters more than images.
Example
wait_until=domcontentloadedAPI optionwait_until
Related: Load event, Network idle, Lazy loading
Loading and timing · Why website screenshots look wrong
E1 term
- Element screenshotAlso: element capture, component screenshot, selector screenshot
An element screenshot is a screenshot of a single element of a page, chosen with a selector, in place of the whole viewport.[15]
Why it matters for a screenshot. Capturing one chart, card or table gives a smaller file with nothing left to crop.
Example
selector=#pricingAPI optionselector
Related: CSS selector, Full-page screenshot, Shadow DOM
Layout and pixels · CSS selectors for element screenshots
F3 terms
- Flaky testAlso: flaky, flake, unstable test
A flaky test is a test that fails on the first run and passes when it is retried, with no change to the code. Playwright reports such a test as flaky.[19][16]
Why it matters for a screenshot. Screenshot tests turn flaky when a page is captured before it has settled, which is why Playwright disables animations and waits until two consecutive screenshots are the same before it compares.
Related: Baseline, Threshold, Lazy loading
Testing · Visual regression testing guide
- Frame rateAlso: fps, frames per second
A frame rate is the number of frames shown each second, written fps. Films typically run at 24 fps, and browsers aim to repaint a page at 60 fps.[30]
Why it matters for a screenshot. In a recording of a scrolling page, a higher frame rate is smoother and stores more frames. CurlShot records at 24 fps by default and accepts 5 to 30.
Example
video_fps=24- Full-page screenshotAlso: full-page capture, full page, whole-page screenshot, scrolling screenshot, long screenshot
A full-page screenshot is a screenshot of the full scrollable page, from the top to the bottom, as if the screen were very tall, in place of only the part visible in the viewport.[15][16]
Why it matters for a screenshot. The width of a full-page screenshot still comes from the viewport and only the height grows, so lazy-loaded images, sticky headers and very tall pages each need handling before the capture.
Example
full_page=trueAPI optionfull_pagefull_page_scrollfull_page_max_height
Related: Viewport, Lazy loading, Sticky positioning
Layout and pixels · Full-page screenshots on every device
G1 term
- GIFAlso: animated GIF, Graphics Interchange Format
GIF is an image format that losslessly compresses 8-bit indexed colour, so a palette holds at most 256 colours, and that supports simple animation.[24]
Why it matters for a screenshot. A GIF of a scrolling page plays wherever an image does, with no video player, but converting a full-colour page to a 256-colour palette can dither it. CurlShot caps a GIF at 15 frames per second.
Example
format=gifAPI optionformat
Related: Frame rate, Container format, Lossless compression
Formats · Website video as MP4, WebM or GIF
H2 terms
- HashAlso: digest, checksum, SHA-256, hash function, fingerprint
A hash is the fixed-length output, also called a digest, that a hash function produces from an input of any length. With a cryptographic hash function such as SHA-256, any change to the input leads to a different output.[40]
Why it matters for a screenshot. Storing the hash of a screenshot file when it is taken lets anyone check later that the file has not been altered: hash the file again and compare.
Example
SHA-256: 256 bits, written as 64 hexadecimal characters (256 / 4)Related: Unix timestamp, Signed URL, Webhook
Security and limits · A web page as evidence
- Headless browserAlso: headless Chrome, headless mode, headless Chromium
A headless browser is a web browser that runs without any visible window, in an unattended environment such as a server. Chrome starts in headless mode with the
--headlessflag.[21]Why it matters for a screenshot. Server-side screenshots are taken by a headless browser: it loads and draws the page as a desktop browser does and saves the result as a file.
Example
google-chrome --headlessRelated: Device emulation, Viewport, User agent
Automation · Screenshot API or your own headless browser
I2 terms
- IframeAlso: inline frame, embedded frame, embed, subframe
An iframe is an HTML element that embeds another document into the current page as a nested browsing context with a document of its own.[10][11]
Why it matters for a screenshot. The document inside an iframe, such as an embedded video, map or payment form, loads separately: DOMContentLoaded does not wait for it, and a selector written for the outer page does not match elements inside it.
Example
<iframe src="https://example.com/map"></iframe>Related: CSS selector, Shadow DOM, Load event
Layout and pixels · CSS selectors for element screenshots
- Image sizeAlso: pixel dimensions, screenshot size, output size, resolution
An image size is the width and height of a screenshot file in pixels, which equals the captured area in CSS pixels multiplied by the device pixel ratio.[3][16]
Why it matters for a screenshot. Image size drives the weight of the file, the sharpness of the text and what a vision model charges to read it, and it comes from two inputs you control: the viewport and the device pixel ratio.
Example
1280 x 1024 at ratio 2 = 2560 x 2048 pxAPI optionimage_widthimage_height
Related: Viewport, Device pixel ratio, Visual token
Layout and pixels · Website thumbnail sizes
J1 term
- JPEGAlso: JPG, .jpg
JPEG is a lossy image format for still images that stores 8 bits each of red, green and blue for every pixel and has no alpha channel.[24]
Why it matters for a screenshot. JPEG suits photographs, but lossy compression blurs text and sharp edges, which screenshots are full of, and a JPEG cannot hold a transparent background.
Example
format=jpeg&image_quality=80API optionformatimage_quality
Related: Lossy compression, PNG, WebP
Formats · PNG, JPEG, WebP or PDF for screenshots
L5 terms
- Lazy loadingAlso: lazy load, loading="lazy", lazy images, deferred images
Lazy loading is a strategy that loads a resource only when it is needed. With
loading="lazy"on an image or an iframe, the browser defers loading until the user scrolls near it.[13][12]Why it matters for a screenshot. Nobody scrolls in an automated capture, so lazy images further down a tall page stay empty unless the capture tool scrolls through the page first. The load event does not wait for them either.
Example
<img loading="lazy" src="photo.jpg" alt="">API optionfull_page_scroll
Related: Full-page screenshot, Load event, Network idle
Loading and timing · Why website screenshots look wrong
- Link unfurlAlso: unfurl, unfurling, link preview, rich preview, link card
A link unfurl is the preview a messaging app attaches to a link posted in a conversation. Slack, which uses the term, crawls the link and builds the preview from the Open Graph and X Card metadata of the page.[32][31]
Why it matters for a screenshot. The image in an unfurl is whatever the page names in
og:image, so a generated screenshot or card placed there is what people see before they click.Related: Open Graph image, Image size, Cache hit
Sharing and previews · Social preview image sizes
- Load eventAlso: load, window.onload, page load, onload
A load event is the browser event that fires when the whole page has loaded, including all dependent resources such as stylesheets, scripts, iframes and images, except those that are loaded lazily.[12][14]
Why it matters for a screenshot. Load is the usual moment to take a screenshot and the default wait condition in Playwright and in CurlShot. Lazy images, and anything a script requests after load, are not covered by it.
Example
wait_until=loadAPI optionwait_until
Related: DOMContentLoaded, Network idle, Lazy loading
Loading and timing · Why website screenshots look wrong
- Lossless compressionAlso: lossless, reversible compression
Lossless compression is a class of data compression that allows the original data to be perfectly reconstructed from the compressed data. PNG and lossless WebP are examples.[25][24]
Why it matters for a screenshot. A lossless screenshot keeps every pixel exactly as the browser drew it, which matters for small text and for comparing two screenshots pixel by pixel.
Related: Lossy compression, PNG, Diff
Formats · PNG, JPEG, WebP or PDF for screenshots
- Lossy compressionAlso: lossy, irreversible compression, image quality, compression artefacts
Lossy compression is a data compression method that discards part of the data to make a file smaller, and the discarded data cannot be restored.[26][47]
Why it matters for a screenshot. Lossy formats such as JPEG make smaller files of photo-heavy pages, but every save loses detail, and heavy compression can make the text in a screenshot hard to read, for people and for vision models.
Example
image_quality=80API optionimage_quality
Related: Lossless compression, JPEG, WebP
Formats · PNG, JPEG, WebP or PDF for screenshots
M2 terms
- MCPAlso: Model Context Protocol, MCP server, MCP tool
MCP, the Model Context Protocol, is an open standard for connecting AI applications to external systems such as data sources and tools.[44][46]
Why it matters for a screenshot. A screenshot service that runs an MCP server can be called by an AI assistant directly. CurlShot offers a
take_screenshottool at its MCP endpoint, so an agent can look at a web page with no custom code in between.Example
"method": "tools/call"Related: Tool call, Vision model, Visual token
AI and agents · Screenshots for AI agents
- Media queryAlso: @media, breakpoint, responsive breakpoint, media feature
A media query is a logical expression that lets CSS and other web languages check aspects of the device or user agent a document is shown in, such as its width or its media type, and apply code only when the check passes.[5][6]
Why it matters for a screenshot. Media queries are why one address has many looks: the viewport width picks the phone or the desktop layout, the media type picks screen or print styles, and the colour scheme picks light or dark.
Example
@media (max-width: 600px) { ... }Related: Viewport, Print media, Dark mode
Layout and pixels · Viewport sizes cheat sheet
N1 term
- Network idleAlso: networkidle, network quiet, idle network
Network idle is a wait condition that treats a page as ready when there have been no network connections for at least 500 ms. That is how Playwright defines its
networkidleoption.[14]Why it matters for a screenshot. Network idle catches content that scripts fetch after the load event, but a page that keeps polling or streaming may never go idle, and the capture then runs into its timeout. Playwright discourages relying on it in tests.
Example
wait_until=networkidleAPI optionwait_until
Related: Load event, Timeout, Lazy loading
Loading and timing · Why website screenshots look wrong
O1 term
- Open Graph imageAlso: og:image, OG image, social preview image, share image, social card
An Open Graph image is the image a page names in its
og:imagemeta tag: an image URL that represents the page when it is shared.og:imageis one of the four required Open Graph properties, withog:title,og:typeandog:url.[31][32]Why it matters for a screenshot. Social networks and messaging apps show the Open Graph image in link previews, and a common way to make one is to render an HTML template to an image.
Example
<meta property="og:image" content="https://example.com/card.png">Related: Link unfurl, Image size, Signed URL
Sharing and previews · HTML to image templates
P6 terms
- Page boxAlso: page area, @page, paper size, A4, Letter
A page box is the rectangular area with a finite width and height that CSS maps to one printed page. The content area of a page box, where the document flows, is called the page area.[50]
Why it matters for a screenshot. A PDF made from a web page is a series of page boxes: the paper size sets the box, the margins shrink the page area, and what does not fit moves to the next page. In CSS, A4 is 210 mm by 297 mm and letter is 8.5 in by 11 in.
Example
@page { size: A4; margin: 20mm; }API optionpdf_paper_formatpdf_marginpdf_landscape
Related: Page-margin box, Page break, PDF
Printing and PDF · Web page to PDF: paper sizes
- Page breakAlso: break-before, page-break-before, break-after, pagination
A page break is the point where content moves on to the next printed page. The CSS property
break-beforewith the valuepageforces a page break right before an element.[51]Why it matters for a screenshot. A screenshot is one continuous image and has no page breaks, while a PDF on a paper size cuts content wherever a page ends unless the CSS of the page says where to break.
Example
h2 { break-before: page; }API optionpdf_fit_one_page
Related: Page box, PDF, Print media
Printing and PDF · Web page to PDF: paper sizes
- Page-margin boxAlso: margin box, running header, running footer, @top-center
A page-margin box is one of the 16 boxes that CSS defines in the margin area of a page box, such as
@top-centeror@bottom-right-corner, typically used for running headers and footers.[50]Why it matters for a screenshot. Page numbers and running headers belong to page-margin boxes, so they exist only in paged output such as a PDF and never in a screenshot.
Example
@page { @bottom-center { content: counter(page); } }Related: Page box, Print media, PDF
Printing and PDF · Web page to PDF: paper sizes
- PDFAlso: Portable Document Format, web page to PDF, print to PDF
PDF, the Portable Document Format, is a file format that presents a document the same way regardless of the software, hardware or operating system used to view it. PDF is an open standard maintained by ISO.[52][14]
Why it matters for a screenshot. Saving a web page as a PDF gives pages of a paper size with text that can be selected and searched, where a screenshot gives one image made of pixels.
Example
format=pdfAPI optionformatpdf_paper_format
Related: Page box, Print media, PNG
Printing and PDF · Web page to PDF: paper sizes
- PNGAlso: Portable Network Graphics, .png
PNG is an image format that uses lossless compression and supports full alpha transparency.[24]
Why it matters for a screenshot. PNG is the safe default for screenshots, because lossless encoding keeps text and sharp edges exact: MDN recommends lossless encoding for screenshots, diagrams and line art. PNG is the default format of CurlShot.
Example
format=pngAPI optionformat
Related: Lossless compression, Alpha channel, WebP
Formats · PNG, JPEG, WebP or PDF for screenshots
- Print mediaAlso: print stylesheet, @media print, media type, screen media, print styles
Print media is the CSS media type
print, intended for paged material and for documents viewed in print preview. Its counterpartscreenis intended primarily for screens.[6][14]Why it matters for a screenshot. Playwright makes a PDF with the print styles of a page by default, and a site may write those to look quite unlike its screen styles. CurlShot goes the other way: a PDF is drawn with screen styles unless
media_type=printis set.Example
@media print { nav { display: none; } }API optionmedia_type
Related: Media query, PDF, Page box
Printing and PDF · Web page to PDF: paper sizes
Q1 term
- QuotaAlso: monthly quota, usage limit, allowance, plan limit
A quota is the number of screenshots a plan allows in one billing period. A quota counts work done over a period of weeks, where a rate limit counts requests in a period of seconds or minutes.
Why it matters for a screenshot. In CurlShot only successful renders count against the quota and a cache hit does not. A request beyond the quota is answered with status
402and the error codequota_exceeded.Example
X-Quota-Remaining: 4997Related: Rate limit, Cache hit, Time to live
Security and limits, a term of the CurlShot API · Bulk screenshots from a list of URLs
R1 term
- Rate limitAlso: rate limiting, 429, Too Many Requests, throttling, Retry-After
A rate limit is a cap on how many requests a client may send in a given amount of time. A server that enforces one answers the extra requests with HTTP status 429 Too Many Requests and may add a
Retry-Afterheader that says how long to wait.[34]Why it matters for a screenshot. Capturing a long list of addresses in a loop is the usual way to reach a rate limit, so a batch job should pace its requests and retry a 429 after a pause.
Example
HTTP/1.1 429 Too Many RequestsRelated: Quota, Timeout, Webhook
Security and limits · Bulk screenshots from a list of URLs
S5 terms
- Screen sizeAlso: screen resolution, display resolution, screen.width, monitor resolution
A screen size is the width and height of the whole display of a device, which browsers report in CSS pixels as
screen.widthandscreen.height. A screen size is a different number from the viewport, which is only the part of the window that shows the page.[4][20][1]Why it matters for a screenshot. A page lays itself out to the viewport, not to the screen, so the size to set for a screenshot is the viewport. The resolution a monitor is sold with, in physical pixels, is a third number again.
Related: Viewport, CSS pixel, Device pixel
Layout and pixels · Viewport sizes cheat sheet
- Shadow DOMAlso: shadow root, shadow tree, web component, shadow host
A shadow DOM is a DOM tree attached to an element and hidden from the JavaScript and CSS running in the page. The element it is attached to is the shadow host, and the tree starts at a shadow root.[9]
Why it matters for a screenshot.
document.querySelectorAlldoes not find elements inside a shadow tree and page CSS does not affect them, so a plain selector or an injected style can miss the inside of a web component.Example
host.attachShadow({ mode: "open" })Related: CSS selector, Iframe, Element screenshot
Layout and pixels · CSS selectors for element screenshots
- Signed URLAlso: signed link, signature, expiring link
A signed URL is a URL that carries a signature in its query string and gives whoever holds the link limited permission, and usually limited time, to make one specific request without other credentials.[38]
Why it matters for a screenshot. A signed screenshot link can sit in a public
imgtag: the signature is computed from the exact parameters and a secret key, so changing the address inside the link breaks it. In CurlShot the parameters aresignatureand, for a lifetime,expires.Example
...&expires=1791083483&signature=b565e2...Related: Unix timestamp, Hash, Cache hit
Sharing and previews · Website thumbnail sizes
- SSRFAlso: server-side request forgery, private address, internal address
SSRF, server-side request forgery, is an attack in which an attacker abuses a feature of a server that fetches URLs to make it read or update internal resources, such as a cloud metadata service at 169.254.169.254 or an internal REST interface.[33]
Why it matters for a screenshot. A screenshot service opens whatever address it is given, which makes it a natural target for SSRF, so it has to refuse addresses that lead to private or internal networks. CurlShot refuses them.
Example
http://169.254.169.254/Related: Rate limit, Webhook, Headless browser
Security and limits · Screenshot API or your own headless browser
- Sticky positioningAlso: position: sticky, sticky header, fixed header, position: fixed, fixed positioning
Sticky positioning is the CSS value
position: sticky, which lays an element out in the normal flow and then offsets it relative to its nearest scrolling ancestor, so it stays in view while that ancestor scrolls.position: fixedtakes an element out of the flow and positions it relative to the viewport.[7]Why it matters for a screenshot. Sticky and fixed headers, cookie bars and chat buttons follow the viewport, so in a full-page screenshot they can land in the middle of the image or cover content. Hiding them by selector is the usual fix.
Example
hide_selectors=.site-headerAPI optionhide_selectors
Related: Full-page screenshot, CSS selector, Cookie banner
Layout and pixels · Why website screenshots look wrong
T5 terms
- ThresholdAlso: tolerance, maxDiffPixels, maxDiffPixelRatio, diff threshold
A threshold is the tolerance of a screenshot comparison. In Playwright the threshold is the acceptable perceived colour difference between the same pixel in two images, from 0 (strict) to 1 (lax) with a default of 0.2, and
maxDiffPixelsseparately caps how many pixels may differ.[16][18]Why it matters for a screenshot. A threshold of zero fails on rendering noise nobody can see and a loose one hides real changes, so the value decides whether a visual test is useful. The pixelmatch library defaults to 0.1.
Example
threshold: 0.2Related: Diff, Baseline, Anti-aliasing
Testing · Visual regression testing guide
- Time to liveAlso: TTL, cache lifetime, max-age, expiry
A time to live, or TTL, is the amount of time, in seconds, during which a cached result may be reused before it expires and has to be produced again.[37][35]
Why it matters for a screenshot. TTL trades freshness for cost: a long one serves the same screenshot many times, a short one renders the page again sooner. In CurlShot
cache_ttldefaults to 14,400 seconds (4 hours) and runs from 60 seconds to 2,592,000 (30 days).Example
cache_ttl=86400 (one day: 24 x 3,600)API optioncache_ttl
Related: Cache hit, Quota, Signed URL
Security and limits · Website change monitoring with screenshots
- TimeoutAlso: navigation timeout, render timeout, time limit
A timeout is the maximum time an operation may take before it is stopped and reported as failed.[14]
Why it matters for a screenshot. A capture waits for the page, and without a timeout a slow or never-idle page would hold a browser for good. In CurlShot the timeout is 30 seconds by default and can be set from 1 to 90.
Example
timeout=30API optiontimeout
Related: Network idle, Load event, Rate limit
Loading and timing · Screenshot code examples
- TokenAlso: tokens, input tokens, tokenizer
A token is the smallest unit of text a language model reads and writes. A token can correspond to a word, a part of a word, a character or a byte.[46][47]
Why it matters for a screenshot. Models are limited and priced by tokens, and an image is counted in tokens too, so the size of a screenshot sent to a model is a cost decision.
Related: Visual token, Vision model, MCP
AI and agents · Screenshots for AI agents
- Tool callAlso: tool use, function calling, function call, tools/call
A tool call is a structured request from a language model to run a named function with arguments. The application or a server runs the function and returns the result to the model. In MCP the request is the
tools/callmethod.[48][45]Why it matters for a screenshot. Taking a screenshot is a typical tool: the model asks for an address, the tool answers with an image block that holds base64 data and a MIME type, and the model then looks at the page.
Example
{ "name": "take_screenshot", "arguments": { "url": "https://example.com" } }Related: MCP, Vision model, Accessibility tree
AI and agents · Screenshots for AI agents
U2 terms
- Unix timestampAlso: timestamp, epoch time, Unix time, epoch seconds
A Unix timestamp is a point in time written as the number of seconds since the epoch, the midnight at the beginning of 1 January 1970 UTC. JavaScript counts the same span in milliseconds.[41]
Why it matters for a screenshot. Timestamps say when a screenshot was taken and when a signed link stops working. In CurlShot the
expiresparameter of a signed link and thex-timestampheader of a webhook are Unix seconds.Example
86400 = 1970-01-02T00:00:00Z (24 x 3,600 seconds after the epoch)- User agentAlso: UA, User-Agent header, user agent string, UA string
A user agent is a program that acts for a person on the web, such as a browser. With each request a browser sends a
User-Agentheader, a string that often identifies the browser, its version and its operating system.[22]Why it matters for a screenshot. A server can read the user agent string and answer with a different page, so the string a capture browser sends can change what is in the screenshot.
Example
User-Agent: Mozilla/5.0 ...API optionuser_agent
Related: Device emulation, Headless browser, Cookie
Automation · Screenshot code examples
V4 terms
- ViewportAlso: browser window size, window size, visual viewport, layout viewport
A viewport is the part of a document that is visible in the browser window. Its width and height are measured in CSS pixels.[1]
Why it matters for a screenshot. The viewport width decides which layout a responsive page shows, and the viewport is exactly the area a screenshot contains unless a full page or one element is asked for. CurlShot uses 1280 x 1024 unless told otherwise.
Example
viewport_width=1280&viewport_height=1024API optionviewport_widthviewport_height
Related: CSS pixel, Screen size, Full-page screenshot
Layout and pixels · Viewport sizes cheat sheet
- Vision modelAlso: multimodal model, image understanding, VLM, vision language model
A vision model is a language model that accepts images as input and can describe and analyse them. Claude, for example, accepts JPEG, PNG, GIF and WebP images of up to 8000 x 8000 pixels.[47]
Why it matters for a screenshot. A vision model reads a screenshot much as a person does, but an image above the limit of the model is scaled down first, on Claude to a long edge of 1568 or 2576 pixels depending on the model, and that can make small text unreadable.
Related: Visual token, Token, Tool call
AI and agents · Screenshots for AI agents
- Visual regression testAlso: visual test, screenshot test, visual comparison, snapshot test
A visual regression test is an automated test that takes a screenshot of a page and compares it with an approved reference screenshot, and fails when the two differ by more than a set tolerance.[17][16]
Why it matters for a screenshot. A visual regression test catches what a functional test does not look at: a layout that broke, an image that went missing or a colour that changed on a page whose buttons still work.
Example
await expect(page).toHaveScreenshot('home.png')Related: Baseline, Diff, Flaky test
Testing · Visual regression testing guide
- Visual tokenAlso: image token, image tokens, image cost, patch
A visual token is the unit in which the Claude models of Anthropic count an image: one patch of 28 x 28 pixels, so an image costs ceil(width / 28) x ceil(height / 28) visual tokens.[47]
Why it matters for a screenshot. Token cost follows pixel count: a 1000 x 1000 screenshot is 36 x 36 = 1,296 visual tokens, so a device pixel ratio of 1 and a capture of only the part that is needed keep the bill down. Other vendors count images in their own ways.
Example
1920 x 1080 = 69 x 39 = 2,691 visual tokens before any downscalingRelated: Vision model, Token, Image size
AI and agents · Screenshots for AI agents
W2 terms
- WebhookAlso: callback, callback URL, HTTP callback, async result
A webhook is an HTTP request that a service sends to a URL you specify when an event happens, so you receive the data as it happens and do not have to poll an API for it.[39]
Why it matters for a screenshot. A slow render can run in the background and announce itself: CurlShot calls the
webhook_urlwhen the job ends and signs the body with HMAC-SHA256, so the receiver can check who sent it.Example
async=true&webhook_url=https://example.com/hooks/screenshotAPI optionwebhook_urlasyncwebhook_sign
Related: Rate limit, Hash, Unix timestamp
Sharing and previews · Bulk screenshots from a list of URLs
- WebPAlso: .webp, lossless WebP, lossy WebP
WebP is an image format that supports both lossy and lossless compression, as well as transparency and animation.[24]
Why it matters for a screenshot. MDN describes WebP as offering much better compression than PNG or JPEG, so a WebP screenshot is usually the lighter file, and it can keep a transparent background.
Example
format=webp
How the terms connect
16 core web capture terms form three chains: the pixels of the file on the left, the moment of capture in the middle, and the comparison of two screenshots on the right. Most confusion about screenshots comes from skipping a step in one of them.
Each line reads downward: the lower term builds on the upper one. Choose a term to see its neighbours.
Viewport
A viewport is the part of a document that is visible in the browser window. Its width and height are measured in CSS pixels.
Builds on
- . Emulating a device sets the viewport, along with the user agent and touch support.
Leads to
- . A viewport is measured in CSS pixels.
Every link of the map, in words
- Headless browserDevice emulationA headless browser has no real screen, so the device it shows a page on is the one it emulates.
- Device emulationViewportEmulating a device sets the viewport, along with the user agent and touch support.
- ViewportCSS pixelA viewport is measured in CSS pixels.
- CSS pixelDevice pixel ratioThe device pixel ratio says how many device pixels draw one CSS pixel along one side.
- Device pixel ratioImage sizeImage size is the captured area in CSS pixels multiplied by the device pixel ratio.
- Headless browserDOMContentLoadedA headless browser loads a page as any browser does and fires the same events.
- DOMContentLoadedLoad eventDOMContentLoaded fires when the HTML is parsed; the load event also waits for stylesheets, scripts, iframes and images.
- Load eventNetwork idleThe load event does not cover requests a script starts afterwards; network idle waits for 500 ms with no connections.
- Network idleLazy loadingA lazy image is not requested until someone scrolls near it, so even an idle network does not mean it has loaded.
- Lazy loadingFull-page screenshotA full-page screenshot has to scroll through the page first, or the lazy images further down are empty.
- Full-page screenshotImage sizeA full-page screenshot keeps the width of the viewport and takes its height from the page.
- Image sizeVisual tokenClaude counts an image in patches of 28 x 28 pixels, so more pixels are more visual tokens.
- BaselineDiffA diff is always a comparison against a baseline.
- DiffThresholdThe threshold decides how different a pixel must be to count in the diff.
- ThresholdFlaky testA tolerance that is too strict can fail on rendering noise, and a test that passes on one run then fails on the next.
- Lazy loadingFlaky testAn image that arrives late changes pixels from one run to the next.
Web capture terms people confuse
9 pairs of terms get used as if they meant the same thing. Each card puts the two side by side and gives the difference in one line.
The part of the window that shows the page. The page lays itself out to it.
The whole display, including what the browser and the system take.
Set the viewport for a screenshot. The screen resolution of a device is not the size of its page.
A unit of layout: 1/96 of a CSS inch. Viewports are measured in it.
One physical dot of the display. Screenshot files are counted in it.
Device pixels = CSS pixels x device pixel ratio.
One tall still image of the whole page, top to bottom.
A recording of the page being scrolled, as MP4, WebM or GIF.
One is a file you read like a page, the other a file you play. Both cover the whole page.
Every pixel can be reconstructed exactly. PNG, lossless WebP.
Data is discarded for a smaller file and cannot be restored. JPEG, lossy WebP.
Lossless for text, interfaces and comparisons. Lossy for photo-heavy pages where size matters.
An event: the page and its stylesheets, scripts, iframes and images have loaded.
A wait condition: no network connections for at least 500 ms.
Load is a moment the browser announces. Network idle is a quiet period a tool measures.
A stored copy is returned. Fast, and the page is as it was when the copy was made.
Fresh render
The page is opened and drawn again. Slower, and current.
A hit trades freshness for speed. The time to live sets how old a copy may get.
Requests in a short time. Passing it gives HTTP 429, and it resets within the window.
Screenshots in a billing period. It resets when the period ends.
A rate limit is about speed, a quota about volume. Slowing down fixes the first, not the second.
Screenshot
One image made of pixels, at a size in pixels. Text is part of the image.
Pages of a paper size, cut where each page ends. Text can be selected and searched.
A screenshot shows how a page looked on a screen. A PDF is the page laid out for paper.
The approved screenshot. An input of the comparison.
The pixels that differ from the baseline. The output of the comparison.
You approve a baseline. You read a diff.
Where to go deeper on each group of terms
A definition tells you what a word means, not what to do about it. Each of the 9 groups has a full guide in this blog and a page in the CurlShot docs.
| Group | Terms | Guides | Docs |
|---|---|---|---|
| Layout and pixelsHow big the page is drawn and which part of it ends up in the file. | TermsCSS pixel, CSS selector, Device pixel, Device pixel ratio, Element screenshot, Full-page screenshot, Iframe, Image size, Media query, Screen size, Shadow DOM, Sticky positioning, Viewport | Guides | Docs |
| Loading and timingWhen a page counts as ready, and what is still missing at that moment. | TermsDOMContentLoaded, Lazy loading, Load event, Network idle, Timeout | Guides | Docs |
| FormatsWhat the file is made of: compression, transparency, frames. | TermsAlpha channel, Codec, Container format, Frame rate, GIF, JPEG, Lossless compression, Lossy compression, PNG, WebP | Guides | Docs |
| AutomationThe browser that takes the screenshot and what it tells the site about itself. | TermsCookie, Dark mode, Device emulation, Headless browser, User agent | Guides | Docs |
| Sharing and previewsGetting a screenshot to people and to other systems. | TermsLink unfurl, Open Graph image, Signed URL, Webhook | Guides | Docs |
| Security and limitsWhat a capture service has to refuse, count, store and prove. | TermsCache hit, Cookie banner, Cookie consent, Hash, Quota, Rate limit, SSRF, Time to live, Unix timestamp | Guides | Docs |
| TestingComparing a new screenshot with an approved one. | TermsAnti-aliasing, Baseline, Diff, Flaky test, Threshold, Visual regression test | Guides | Docs |
| AI and agentsHow a model asks for a screenshot and what reading one costs. | TermsAccessibility tree, MCP, Token, Tool call, Vision model, Visual token | Guides | Docs |
| Printing and PDFA page laid out for paper in place of a screen. | TermsPage box, Page break, Page-margin box, PDF, Print media | Guides | Docs |
Questions people ask
What is the difference between a viewport and a screen resolution?
A viewport is the part of the browser window that shows the page, and a page lays itself out to it. A screen resolution describes the whole display. For a screenshot the number to set is the viewport, in CSS pixels.
What does device pixel ratio mean for a screenshot?
Device pixel ratio is the number of device pixels that draw one CSS pixel along one side. It multiplies the pixel size of a screenshot without changing the layout: a 1280 x 1024 viewport at ratio 2 gives a 2560 x 2048 pixel file with sharper text.
What is the difference between the load event and network idle?
The load event is fired by the browser when the page and its stylesheets, scripts, iframes and images have loaded, except lazy ones. Network idle is a wait condition a tool measures: in Playwright, no network connections for at least 500 ms. Network idle also covers requests that scripts start after load.
What is a full-page screenshot?
A full-page screenshot is a screenshot of the full scrollable page, from top to bottom, as if the screen were very tall. Its width still comes from the viewport. Lazy-loaded images need the page to be scrolled before the capture, or they are empty.
What is the difference between a rate limit and a quota?
A rate limit caps how many requests a client may send in a short time, and a server signals it with HTTP status 429. A quota caps how many screenshots a plan allows in a billing period. In CurlShot a request beyond the quota gets status 402 and a cache hit does not count against it.
Can I link to a single definition in the glossary?
Yes. Every term has an address of its own: the address of the glossary followed by # and the id of the term, for example #device-pixel-ratio. Each entry has a copy link control that puts that address on the clipboard.
Sources
- [1]MDN Web Docs, Viewport (glossary). Checked .
- [2]MDN Web Docs, CSS pixel (glossary). Checked .
- [3]MDN Web Docs, Window: devicePixelRatio property. Checked .
- [4]MDN Web Docs, Screen: width property. Checked .
- [5]MDN Web Docs, Media query (glossary). Checked .
- [6]MDN Web Docs, @media: media types and media features. Checked .
- [7]MDN Web Docs, position: sticky and fixed. Checked .
- [8]MDN Web Docs, CSS selector (glossary). Checked .
- [9]MDN Web Docs, Using shadow DOM. Checked .
- [10]MDN Web Docs, <iframe>: the inline frame element. Checked .
- [11]MDN Web Docs, Document: DOMContentLoaded event. Checked .
- [12]MDN Web Docs, Window: load event. Checked .
- [13]MDN Web Docs, Lazy loading. Checked .
- [14]Playwright, Page: goto (waitUntil, timeout), pdf and emulateMedia. Checked .
- [15]Playwright, Screenshots. Checked .
- [16]Playwright, PageAssertions: toHaveScreenshot options. Checked .
- [17]Playwright, Visual comparisons. Checked .
- [18]Mapbox on GitHub, pixelmatch: README. Checked .
- [19]Playwright, Retries. Checked .
- [20]Playwright, Emulation. Checked .
- [21]Chrome for Developers, Chrome Headless mode. Checked .
- [22]MDN Web Docs, User agent (glossary). Checked .
- [23]MDN Web Docs, Using HTTP cookies. Checked .
- [24]MDN Web Docs, Image file type and format guide. Checked .
- [25]MDN Web Docs, Lossless compression (glossary). Checked .
- [26]MDN Web Docs, Lossy compression (glossary). Checked .
- [27]MDN Web Docs, Alpha (glossary). Checked .
- [28]MDN Web Docs, Codec (glossary). Checked .
- [29]MDN Web Docs, Media container formats. Checked .
- [30]MDN Web Docs, Frame rate (glossary). Checked .
- [31]ogp.me, The Open Graph protocol. Checked .
- [32]Slack developer docs, Unfurling links in messages. Checked .
- [33]OWASP, Server Side Request Forgery. Checked .
- [34]IETF, RFC 6585: Additional HTTP Status Codes, section 4 (429 Too Many Requests). Checked .
- [35]MDN Web Docs, HTTP caching. Checked .
- [36]Cloudflare docs, Cloudflare cache responses. Checked .
- [37]MDN Web Docs, TTL (glossary). Checked .
- [38]Google Cloud Storage docs, Signed URLs. Checked .
- [39]GitHub Docs, About webhooks. Checked .
- [40]MDN Web Docs, Hash function (glossary). Checked .
- [41]MDN Web Docs, Date: the epoch and timestamps. Checked .
- [42]European Union, Your Europe, Online privacy: cookies. Checked .
- [43]Information Commissioner’s Office (UK), How do we manage consent in practice?. Checked .
- [44]Model Context Protocol, What is the Model Context Protocol (MCP)?. Checked .
- [45]Model Context Protocol, Specification 2025-06-18: Tools. Checked .
- [46]Anthropic, Claude docs, Glossary: tokens, context window, MCP. Checked .
- [47]Anthropic, Claude docs, Vision: image limits, formats and token cost. Checked .
- [48]Anthropic, Claude docs, Tool use with Claude. Checked .
- [49]MDN Web Docs, Accessibility tree (glossary). Checked .
- [50]W3C, CSS Paged Media Module Level 3. Checked .
- [51]MDN Web Docs, break-before. Checked .
- [52]Adobe, What is a PDF?. Checked .
- [53]MDN Web Docs, font-smooth. Checked .
Read next
- Cheat sheetViewport sizes cheat sheet: phones to desktopsViewport sizes in CSS pixels, screenshot sizes and device pixel ratios of iPhone, Pixel, Galaxy, iPad and laptop screens, drawn to scale, and the sizes to test.
- Field guideWhy website screenshots look wrong, and the fixesA field guide to 11 ways a website screenshot goes wrong, from blank lazy images to cookie banners and cut-off pages, with the cause and the fix for each.
- ExplainerScreenshots for AI agents: let a model see a pageWhen to give an AI agent a screenshot, HTML, markdown or the accessibility tree, what a screenshot costs in tokens on each vendor, and how to wire it up.