/screenshot
POST/screenshot
Returns a screenshot binary from a url or html payload.
"url" or "html" payload in your request. Many options exist including
cookies, user-agents, setting timers and network mocks.
Note: This is the preferred endpoint. The /chromium/screenshot route is equivalent.
Request
Query Parameters
Possible values: [datacenter, residential]
Possible values: [0, 1, false, true]
Possible values: [0, 1, false, true]
Body
- Schema
- JSON
- Array [
- ]
- Array [
- ]
- Array [
- CookiePartitionKey
- string
- ]
- PuppeteerLifeCycleEvent[]
- string
- Array [
- ]
- object
- null
- Array [
- Headers
- AnyRecord
- ]
- Array [
- ]
- Array [
- ]
Whether to automatically block cookie consent modals and popups.
options object
Screenshot options based on Puppeteer's ScreenshotOptions interface.
Includes properties like type, quality, fullPage, clip, etc.
Possible values: [jpeg, png, webp]
Quality of the image, between 0-100. Not applicable to png images.
Capture the screenshot from the surface, rather than the view.
When true, takes a screenshot of the full page.
Hides default white background and allows capturing screenshots with transparency.
clip object
Specifies the region of the page/element to clip.
the width of the element in pixels.
the height of the element in pixels.
Encoding of the image.
Possible values: [base64, binary]
Capture the screenshot beyond the viewport.
addScriptTag object[]
An array of script tags to add to the page before performing actions.
Each object can contain either a url or a content property. path is rejected.
addStyleTag object[]
An array of style tags to add to the page before performing actions.
Each object can contain either a url or a content property. path is rejected.
authenticate object
Credentials for HTTP authentication. Contains username and password properties.
When bestAttempt is set to true, browserless will attempt to proceed when "awaited" events fail or timeout. This includes things like goto, waitForSelector, and more.
cookies object[]
An array of cookies to set on the page before navigation.
Each cookie object should contain at least name and value properties.
Cookie name.
Cookie value.
The request-URI to associate with the setting of the cookie. This value can affect the default domain, path, and source scheme values of the created cookie.
Cookie domain.
Cookie path.
True if cookie is secure.
True if cookie is http-only.
Cookie SameSite type.
Possible values: [Default, Lax, None, Strict]
Cookie expiration date, session cookie if not set
Cookie Priority. Supported only in Chrome.
Possible values: [High, Low, Medium]
Cookie source scheme type. Supported only in Chrome.
Possible values: [NonSecure, Secure, Unset]
partitionKey object
Cookie partition key. In Chrome, it matches the top-level site the partitioned cookie is available in. In Firefox, it matches the source origin in the {@link https://w3c.github.io/webdriver-bidi/#type-storage-PartitionKey PartitionKey}.
Represents a cookie partition key in Chrome.
The site of the top-level URL the browser was visiting at the start of the request to the endpoint that set the cookie.
In Chrome, maps to the CDP's topLevelSite partition key.
Indicates if the cookie has any ancestors that are cross-site to the topLevelSite.
Supported only in Chrome.
Changes the CSS media type of the page. Accepts values like "screen" or "print".
gotoOptions object
Options to configure the page navigation, such as timeout and waitUntil.
If provided, it will take preference over the referer header value set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.
If provided, it will take preference over the referer-policy header value set by {@link Page.setExtraHTTPHeaderspage.setExtraHTTPHeaders()}.
Maximum wait time in milliseconds. Pass 0 to disable the timeout.
The default value can be changed by using the {@link Page.setDefaultTimeout} or {@link Page.setDefaultNavigationTimeout} methods.
waitUntil object
When to consider waiting succeeds. Given an array of event strings, waiting is considered to be successful after all events have been fired.
Possible values: [domcontentloaded, load, networkidle0, networkidle2]
signal object
A signal object that allows you to cancel the call.
onabort objectrequired
HTML content to set as the page content instead of navigating to a URL.
An array of patterns to match against request URLs for automatic rejection. Requests matching these patterns will be aborted.
An array of resource types to reject during page load. Common types include "image", "stylesheet", "font", "script", etc.
Possible values: [cspviolationreport, document, eventsource, fedcm, fetch, font, image, manifest, media, other, ping, prefetch, preflight, script, signedexchange, stylesheet, texttrack, websocket, xhr]
requestInterceptors object[]
An array of request interceptors that can modify or mock network requests.
Each interceptor has a pattern to match URLs and a response to return.
An array of patterns (using req.url().match(r.pattern) to match) and their
corresponding responses to use in order to fulfill those requests.
response objectrequired
headers object
Optional response headers. Either a {@link https://developer.mozilla.org/en-US/docs/Web/API/Headers Headers} instance or a plain record.
The record values will be converted to string following: Arrays' values will be mapped to String (Used when you need multiple headers with the same name). Non-arrays will be converted to String.
A string representation of the body to return. Can be a base64-encoded string but please omit any leading content-type data (eg "data:image/png;base64,").
setExtraHTTPHeaders object
An object containing additional HTTP headers to send with every request.
Whether or not to allow JavaScript to run on the page.
The URL to navigate to before performing actions.
userAgent object
The user agent string to use for the page.
userAgentMetadata object
Used to specify User Agent Client Hints to emulate. See https://wicg.github.io/ua-client-hints Missing optional values will be filled in by the target with what it would normally use.
brands object[]
Brands appearing in Sec-CH-UA.
fullVersionList object[]
Brands appearing in Sec-CH-UA-Full-Version-List.
Used to specify User Agent form-factor values. See https://wicg.github.io/ua-client-hints/#sec-ch-ua-form-factors
viewport object
The viewport dimensions and settings for the page.
Includes properties like width, height, deviceScaleFactor, etc.
The page width in CSS pixels.
The page height in CSS pixels.
Specify device scale factor. See {@link https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio devicePixelRatio} for more info.
Whether the meta viewport tag is taken into account.
Specifies if the viewport is in landscape mode.
Specify if the viewport supports touch events.
waitForEvent object
Options for waiting for a specific event to be fired on the page.
waitForFunction object
Options for waiting for a JavaScript function to execute.
The function, or statement, to be evaluated in browser context
An interval at which the pageFunction is executed, defaults to raf. If polling is a number, then it is treated as an interval in milliseconds at which the function would be executed. If polling is a string, then it can be one of the following values: "raf" or "mutation"
Maximum time to wait for in milliseconds. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
waitForSelector object
Options for waiting for a specific CSS selector to appear on the page.
The amount of time in milliseconds to wait before proceeding.
Whether to scroll through the entire page before capturing content. Useful for triggering lazy-loaded content.
A CSS selector to target a specific element instead of the full page.
{
"blockConsentModals": true,
"options": {
"optimizeForSpeed": true,
"type": "jpeg",
"quality": 0,
"fromSurface": true,
"fullPage": true,
"omitBackground": true,
"clip": {
"scale": 0,
"width": 0,
"height": 0,
"x": 0,
"y": 0
},
"encoding": "base64",
"captureBeyondViewport": true
},
"addScriptTag": [
{
"url": "string",
"content": "string",
"type": "string",
"id": "string"
}
],
"addStyleTag": [
{
"url": "string",
"content": "string"
}
],
"authenticate": {
"username": "string",
"password": "string"
},
"bestAttempt": true,
"cookies": [
{
"name": "string",
"value": "string",
"url": "string",
"domain": "string",
"path": "string",
"secure": true,
"httpOnly": true,
"sameSite": "Default",
"expires": 0,
"priority": "High",
"sourceScheme": "NonSecure",
"partitionKey": {
"sourceOrigin": "string",
"hasCrossSiteAncestor": true
}
}
],
"emulateMediaType": "string",
"gotoOptions": {
"referer": "string",
"referrerPolicy": "string",
"timeout": 0,
"waitUntil": [
"domcontentloaded"
],
"signal": {
"aborted": true,
"onabort": {},
"reason": {}
}
},
"html": "string",
"rejectRequestPattern": [
"string"
],
"rejectResourceTypes": [
"cspviolationreport"
],
"requestInterceptors": [
{
"pattern": "string",
"response": {
"headers": {},
"status": 0,
"contentType": "string",
"body": "string"
}
}
],
"setExtraHTTPHeaders": {},
"setJavaScriptEnabled": true,
"url": "string",
"userAgent": {
"userAgent": "string",
"userAgentMetadata": {
"brands": [
{
"brand": "string",
"version": "string"
}
],
"fullVersionList": [
{
"brand": "string",
"version": "string"
}
],
"fullVersion": "string",
"platform": "string",
"platformVersion": "string",
"architecture": "string",
"model": "string",
"mobile": true,
"bitness": "string",
"wow64": true,
"formFactors": [
"string"
]
},
"platform": "string"
},
"viewport": {
"width": 0,
"height": 0,
"deviceScaleFactor": 0,
"isMobile": true,
"isLandscape": true,
"hasTouch": true
},
"waitForEvent": {
"event": "string",
"timeout": 0
},
"waitForFunction": {
"fn": "string",
"polling": "string",
"timeout": 0
},
"waitForSelector": {
"hidden": true,
"selector": "string",
"timeout": 0,
"visible": true
},
"waitForTimeout": 0,
"scrollPage": true,
"selector": "string"
}
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 429
- 500
- 503
Response can either be a text/plain base64 encoded body or a binary stream with png/jpeg as a content-type
- image/png
- image/jpeg
- text/plain
Schema
- Fields
- Example (auto)
"string"
Schema
- Fields
- Example (auto)
"string"
Schema
- Fields
- Example (auto)
"string"
The request contains errors or didn't properly encode content.
The request is missing, or contains bad, authorization credentials.
The request targets a destination that is not allowed.
Resource couldn't be found.
The request took has taken too long to process.
Too many requests are currently being processed.
An internal error occurred when handling the request.
Service is unavailable.