Screenshots_
Capture webpage screenshots with customizable viewport, theme, browser settings, and geolocation options for comprehensive web page documentation.
6 min read
The screenshots endpoint allows you to capture full webpage screenshots with extensive customization options. You can control the browser viewport size, theme, user agent, geolocation, permissions, and other browser settings to capture web pages exactly as they would appear in different scenarios.
This is valuable for various use cases, including generating visual documentation, creating link previews, automating QA testing across different devices and browsers, or archiving web pages for compliance and record-keeping. Instead of manually taking screenshots or setting up complex headless browser infrastructure, you can generate high-quality screenshots on-demand through a simple API call, ensuring consistency and saving development time.
Get webpage screenshot
Capture a screenshot of a remote webpage with customizable browser settings and viewport options.
Parameters
The getScreenshot method accepts the following parameters:
| Parameter | Type | Description |
|---|---|---|
| url | string | The URL of the website to capture. Must be a valid HTTP or HTTPS URL. |
| headers | object | HTTP headers to send with the browser request. Pass a key-value object with custom headers. Defaults to {} if not provided. |
| viewportWidth | integer | The width of the browser viewport in pixels. Accepts values between 1-1920. Defaults to 1280 if not provided. |
| viewportHeight | integer | The height of the browser viewport in pixels. Accepts values between 1-1080. Defaults to 720 if not provided. |
| scale | float | The device pixel ratio for the screenshot. Accepts values between 0.1-3 for different DPI settings. Defaults to 1 if not provided. |
| theme | string | The browser color scheme theme. Accepts: light or dark. Defaults to light if not provided. |
| userAgent | string | A custom user agent string for the browser request. Defaults to browser default if not provided. |
| fullpage | boolean | Capture the full scrollable page (true) or only the viewport (false). Defaults to false if not provided. |
| locale | string | The browser locale code (e.g., en-US, fr-FR). Defaults to browser default if not provided. |
| timezone | string | IANA timezone identifier (e.g., America/New_York, Europe/London). Defaults to browser default if not provided. |
| latitude | float | Geolocation latitude for the screenshot. Accepts values between -90 to 90. Defaults to 0 if not provided. |
| longitude | float | Geolocation longitude for the screenshot. Accepts values between -180 to 180. Defaults to 0 if not provided. |
| accuracy | float | Geolocation accuracy in meters. Accepts values between 0-100000. Defaults to 0 if not provided. |
| touch | boolean | Enable touch device support (true) or disable it (false). Defaults to false if not provided. |
| permissions | array | Array of browser permissions to grant. Accepts: geolocation, camera, microphone, notifications, midi, push, clipboard-read, clipboard-write, payment-handler, usb, bluetooth, accelerometer, gyroscope, magnetometer, ambient-light-sensor, background-sync, persistent-storage, screen-wake-lock, web-share, xr-spatial-tracking. Defaults to [] if not provided. |
| sleep | integer | Wait time in seconds before taking the screenshot. Accepts values between 0-10. Defaults to 0 if not provided. |
| width | integer | The output image width in pixels. Pass 0 to use original width, or 1-2000 for custom width. Defaults to 0 (original width) if not provided. |
| height | integer | The output image height in pixels. Pass 0 to use original height, or 1-2000 for custom height. Defaults to 0 (original height) if not provided. |
| quality | integer | Screenshot quality. Accepts values between 0-100. -1 preserves original image quality. Defaults to -1 if not provided. |
| output | string | Output image format. Supported formats: jpg, jpeg, png, gif, webp. Defaults to png if not provided. |
Viewport customization
Control the browser viewport to capture web pages as they would appear on different devices and screen sizes.
Browser customization
Customize browser settings like theme, user agent, locale, and timezone to simulate different browser environments.
Geolocation simulation
Simulate different geographic locations to see how web pages render with location-based content and features.
Wait time before capture
Use the sleep parameter to wait for a specified duration before capturing the screenshot. This is useful when pages need time to fully load dynamic content, animations, or async resources.
Browser permissions
Grant specific browser permissions to allow web pages to access features like geolocation, camera, microphone, and other APIs during screenshot capture. When you visit a web page that requires certain browser capabilities, it typically prompts users to grant permissions. With the permissions parameter, you can pre-grant these permissions to the browser session, allowing you to capture screenshots of pages that depend on these features without manual intervention.
Available permissions
The following permissions can be granted to the browser session:
| Permission | Description |
|---|---|
geolocation | Access device location coordinates |
camera | Access camera for video/photo capture |
microphone | Access microphone for audio recording |
notifications | Send browser notifications |
midi | Access MIDI devices for music applications |
push | Receive push notifications |
clipboard-read | Read from clipboard |
clipboard-write | Write to clipboard |
payment-handler | Handle payment requests |
usb | Access USB devices |
bluetooth | Access Bluetooth devices |
accelerometer | Access device accelerometer sensor |
gyroscope | Access device gyroscope sensor |
magnetometer | Access device magnetometer sensor |
ambient-light-sensor | Access ambient light sensor |
background-sync | Sync data in the background |
persistent-storage | Use persistent storage |
screen-wake-lock | Prevent screen from sleeping |
web-share | Use Web Share API |
xr-spatial-tracking | Track spatial positioning for XR/VR |
By pre-granting permissions, you can capture screenshots of fully functional pages in their active state, rather than showing permission prompts or degraded experiences.
Use cases
Screenshots are commonly used for:
- Web documentation: Automatically generate visual documentation of web applications and websites
- Link previews: Display website previews in link cards and social sharing interfaces
- Performance testing: Capture pages in different browser environments to verify responsive design
- Accessibility testing: Generate screenshots with different viewport sizes and accessibility settings
- Localization testing: Verify how pages render in different locales and timezones
- Browser compatibility: Test how pages appear with different user agents and browser settings
- Content archival: Create visual snapshots of web pages for archival and reference
- A/B testing: Compare visual renderings of different page variants
- Automated reporting: Generate visual reports and dashboards with live web page screenshots
- QA automation: Verify visual consistency across different browser and device configurations
Was this page helpful?
Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.