Web Scraping Options
Customize web scraping with ScreenshotMAX API
Example of https://news.ycombinator.com scrape
Credentials
access_key
This parameter is used to authenticate API requests. It should be a string with a maximum length of 24 characters. Every request to the ScreenshotMAX API must include a valid access_key, which identifies the calling account. Example: access_key=abcd1234efgh5678ijkl9012.
signature
This parameter is used to verify the authenticity of the request. It should be a string with a maximum length of 64 characters. The signature is generated using the access_key and your secret key, ensuring that the request has not been tampered with. Example: signature=abcd1234efgh5678ijkl9012mnop3456.
Essential
url
Defines the target webpage to capture. This parameter must be a valid URL.
You can pass the URL as either a plain string or a percent-encoded string.
Use encoded format when the URL contains query parameters to avoid conflicts with the API’s own querystring.
Examples:
- Plain:
url=https://www.example.com - Encoded:
url=https%3A%2F%2Fwww.example.com%3Fparam1%3Dvalue1%26param2%3Dvalue2
format
This parameter specifies the output format of the scraped content.
Default value: html
Example:
format=md
Supported values:
| Format | Description |
|---|---|
html | Raw HTML content of the page |
md | Markdown representation of the page |
js_enabled
This parameter indicates whether to enable JavaScript execution on the page. It is a boolean value with a default of true. When set to true, the API will execute JavaScript on the page before scraping.
GPU
gpu_rendering
This parameter determines whether to enable GPU rendering for the webpage. It should be a boolean value, with a default of false. Enabling GPU rendering can improve the quality of the capture for complex webpages. Example: gpu_rendering=true.
Viewport
This section describes the parameters used to control the viewport settings for captures. These parameters can help simulate different devices and screen sizes.
capture_beyond_viewport
This parameter allows capturing content beyond the viewport. It is a boolean value with a default of false. When set to true, the API will capture content that is not currently visible in the viewport. Example: capture_beyond_viewport=true.
viewport_device
This parameter specifies the device type to simulate for the viewport.
It should be a string that matches one of the supported device names.
Using this parameter allows the API to emulate different screen sizes and behaviors when capturing screenshots.
Example:
viewport_device=iphone_13
The full list of supported devices is available via the /devices endpoint.
More information →
viewport_width
This parameter sets the width of the viewport in pixels. It must be an integer greater than or equal to 0. Adjusting the viewport width can help capture screenshots that match specific screen sizes. Example: viewport_width=1280.
viewport_height
This parameter sets the height of the viewport in pixels. It must be an integer greater than or equal to 0. Adjusting the viewport height can help capture screenshots that match specific screen sizes. Example: viewport_height=720.
viewport_landscape
This parameter specifies whether the viewport should be in landscape mode. It is a boolean value. Setting this to true will change the orientation of the viewport. Example: viewport_landscape=true.
viewport_has_touch
This parameter indicates whether the viewport has touch capabilities. It is a boolean value. This affects how the page is rendered and can be useful for mobile simulations. Example: viewport_has_touch=true.
viewport_mobile
This parameter indicates whether the viewport is a mobile device. It is a boolean value. Setting this to true will simulate a mobile device environment. Example: viewport_mobile=true.
device_scale_factor
This parameter determines the device scale factor for the viewport. It should be a number between 1 and 5. This affects the pixel density of the screen. Example: device_scale_factor=2.
Blocking
This section describes the parameters used to block certain elements or resources during the rendering process of the webpage. These parameters help enhance capture speed and content quality by removing unnecessary elements.
block_annoyance
This parameter specifies the type of annoyance to block during the capture.
It should be a string that matches one of the supported values.
Default value: cookies_banner
Example:
block_annoyance=ads
Supported values:
| Value | Description |
|---|---|
| none | No blocking; capture the page as-is |
| ads | Block advertisements |
| tracking | Block tracking scripts and pixels |
| cookies_banner | Block cookie consent banners (default) |
block_ressources
This parameter specifies the types of resources to block during the capture.
It should be an array of strings that match the supported resource types.
Example:
block_ressources=image&block_ressources=stylesheet
Supported resource types:
| Resource Type | Description |
|---|---|
| document | Main HTML documents |
| stylesheet | CSS stylesheets |
| image | Images (e.g., JPEG, PNG, SVG) |
| media | Audio and video files |
| font | Web fonts |
| script | JavaScript files |
| texttrack | Text tracks for media (e.g., subtitles) |
| xhr | XMLHttpRequests (AJAX calls) |
| fetch | Fetch API requests |
| eventsource | Server-Sent Events (SSE) |
| websocket | WebSocket connections |
| manifest | Web app manifests |
| other | Other types not explicitly listed above |
Use the block_resources option to optimize scraping performance by preventing the loading of non-essential assets such as images, fonts, and third-party scripts.
Blocking these resources reduces page load time, lowers bandwidth usage, and speeds up the overall scraping process—especially on media-heavy sites.
Emulation
This section describes the parameters used to control the emulation behavior for captures. These parameters can help simulate different environments and conditions for capturing webpages.
media_type
This parameter specifies the media type for the webpage. It should be a string that matches either screen or print, with a default of screen. This affects how the page is rendered. Example: media_type=print.
Customization
This section describes the parameters used to customize the capture process. These parameters can help tailor the capture to specific needs or preferences.
hide_selectors
This parameter specifies selectors to hide during the capture. It should be an array of strings. This can be useful for removing unwanted elements from the content. Example: hide_selectors=.ad-banner&hide_selectors=.popup.
click_selector
This parameter specifies a selector to click before taking the capture. It should be a string. This allows for interacting with the page before capturing. Example: click_selector=.start-button.
Geolocation
The geolocation parameters allow you to simulate different geographical locations and conditions in your tests. This can be useful for testing location-based features or services.
geolocation_accuracy
This parameter sets the accuracy level for geolocation. It must be an integer between 0 and 1,000. This can help simulate different geolocation scenarios. Example: geolocation_accuracy=200.
geolocation_latitude
This parameter specifies the latitude for geolocation. It must be a number between -90 and 90. This allows for simulating different geographical locations. Example: geolocation_latitude=37.7749.
geolocation_longitude
This parameter specifies the longitude for geolocation. It must be a number between -180 and 180. This allows for simulating different geographical locations. Example: geolocation_longitude=-122.4194.
Request
This section describes the parameters that can be used in the request to the API.
timezone
his parameter specifies the time zone for the capture.
It should be a string that matches one of the supported time zone names.
This helps simulate different local times during the capture process.
Example:
timezone=America/Los_Angeles
Supported values:
| Timezone |
|---|
| Africa/Abidjan |
| Africa/Accra |
| Africa/Addis_Ababa |
| Africa/Algiers |
| Africa/Asmara |
| Africa/Bamako |
| Africa/Bangui |
| Africa/Banjul |
| Africa/Bissau |
| Africa/Blantyre |
| Africa/Brazzaville |
| Africa/Bujumbura |
| Africa/Cairo |
| Africa/Casablanca |
| Africa/Ceuta |
| Africa/Conakry |
| Africa/Dakar |
| Africa/Dar_es_Salaam |
| Africa/Djibouti |
| Africa/Douala |
| Africa/El_Aaiun |
| Africa/Freetown |
| Africa/Gaborone |
| Africa/Harare |
| Africa/Johannesburg |
| Africa/Juba |
| Africa/Kampala |
| Africa/Khartoum |
| Africa/Kigali |
| Africa/Kinshasa |
| Africa/Lagos |
| Africa/Libreville |
| Africa/Lome |
| Africa/Luanda |
| Africa/Lubumbashi |
| Africa/Lusaka |
| Africa/Malabo |
| Africa/Maputo |
| Africa/Maseru |
| Africa/Mbabane |
| Africa/Mogadishu |
| Africa/Monrovia |
| Africa/Nairobi |
| Africa/Ndjamena |
| Africa/Niamey |
| Africa/Nouakchott |
| Africa/Ouagadougou |
| Africa/Porto-Novo |
| Africa/Sao_Tome |
| Africa/Tripoli |
| Africa/Tunis |
| Africa/Windhoek |
| America/Adak |
| America/Anchorage |
| America/Anguilla |
| America/Antigua |
| America/Araguaina |
| America/Argentina/Buenos_Aires |
| America/Argentina/Catamarca |
| America/Argentina/Cordoba |
| America/Argentina/Jujuy |
| America/Argentina/La_Rioja |
| America/Argentina/Mendoza |
| America/Argentina/Rio_Gallegos |
| America/Argentina/Salta |
| America/Argentina/San_Juan |
| America/Argentina/San_Luis |
| America/Argentina/Tucuman |
| America/Argentina/Ushuaia |
| America/Aruba |
| America/Asuncion |
| America/Atikokan |
| America/Bahia |
| America/Bahia_Banderas |
| America/Barbados |
| America/Belem |
| America/Belize |
| America/Blanc-Sablon |
| America/Boa_Vista |
| America/Bogota |
| America/Boise |
| America/Cambridge_Bay |
| America/Campo_Grande |
| America/Cancun |
| America/Caracas |
| America/Cayenne |
| America/Cayman |
| America/Chicago |
| America/Chihuahua |
| America/Ciudad_Juarez |
| America/Costa_Rica |
| America/Creston |
| America/Cuiaba |
| America/Curacao |
| America/Danmarkshavn |
| America/Dawson |
| America/Dawson_Creek |
| America/Denver |
| America/Detroit |
| America/Dominica |
| America/Edmonton |
| America/Eirunepe |
| America/El_Salvador |
| America/Fort_Nelson |
| America/Fortaleza |
| America/Glace_Bay |
| America/Goose_Bay |
| America/Grand_Turk |
| America/Grenada |
| America/Guadeloupe |
| America/Guatemala |
| America/Guayaquil |
| America/Guyana |
| America/Halifax |
| America/Havana |
| America/Hermosillo |
| America/Indiana/Indianapolis |
| America/Indiana/Knox |
| America/Indiana/Marengo |
| America/Indiana/Petersburg |
| America/Indiana/Tell_City |
| America/Indiana/Vevay |
| America/Indiana/Vincennes |
| America/Indiana/Winamac |
| America/Inuvik |
| America/Iqaluit |
| America/Jamaica |
| America/Juneau |
| America/Kentucky/Louisville |
| America/Kentucky/Monticello |
| America/Kralendijk |
| America/La_Paz |
| America/Lima |
| America/Los_Angeles |
| America/Lower_Princes |
| America/Maceio |
| America/Managua |
| America/Manaus |
| America/Marigot |
| America/Martinique |
| America/Matamoros |
| America/Mazatlan |
| America/Menominee |
| America/Merida |
| America/Metlakatla |
| America/Mexico_City |
| America/Miquelon |
| America/Moncton |
| America/Monterrey |
| America/Montevideo |
| America/Montserrat |
| America/Nassau |
| America/New_York |
| America/Nome |
| America/Noronha |
| America/North_Dakota/Beulah |
| America/North_Dakota/Center |
| America/North_Dakota/New_Salem |
| America/Nuuk |
| America/Ojinaga |
| America/Panama |
| America/Paramaribo |
| America/Phoenix |
| America/Port-au-Prince |
| America/Port_of_Spain |
| America/Porto_Velho |
| America/Puerto_Rico |
| America/Punta_Arenas |
| America/Rankin_Inlet |
| America/Recife |
| America/Regina |
| America/Resolute |
| America/Rio_Branco |
| America/Santarem |
| America/Santiago |
| America/Santo_Domingo |
| America/Sao_Paulo |
| America/Scoresbysund |
| America/Sitka |
| America/St_Barthelemy |
| America/St_Johns |
| America/St_Kitts |
| America/St_Lucia |
| America/St_Thomas |
| America/St_Vincent |
| America/Swift_Current |
| America/Tegucigalpa |
| America/Thule |
| America/Tijuana |
| America/Toronto |
| America/Tortola |
| America/Vancouver |
| America/Whitehorse |
| America/Winnipeg |
| America/Yakutat |
| America/Yellowknife |
| Antarctica/Casey |
| Antarctica/Davis |
| Antarctica/DumontDUrville |
| Antarctica/Macquarie |
| Antarctica/Mawson |
| Antarctica/McMurdo |
| Antarctica/Palmer |
| Antarctica/Rothera |
| Antarctica/Syowa |
| Antarctica/Troll |
| Antarctica/Vostok |
| Arctic/Longyearbyen |
| Asia/Aden |
| Asia/Almaty |
| Asia/Amman |
| Asia/Anadyr |
| Asia/Aqtau |
| Asia/Aqtobe |
| Asia/Ashgabat |
| Asia/Atyrau |
| Asia/Baghdad |
| Asia/Bahrain |
| Asia/Baku |
| Asia/Bangkok |
| Asia/Barnaul |
| Asia/Beirut |
| Asia/Bishkek |
| Asia/Brunei |
| Asia/Chita |
| Asia/Choibalsan |
| Asia/Colombo |
| Asia/Damascus |
| Asia/Dhaka |
| Asia/Dili |
| Asia/Dubai |
| Asia/Dushanbe |
| Asia/Famagusta |
| Asia/Gaza |
| Asia/Hebron |
| Asia/Ho_Chi_Minh |
| Asia/Hong_Kong |
| Asia/Hovd |
| Asia/Irkutsk |
| Asia/Jakarta |
| Asia/Jayapura |
| Asia/Jerusalem |
| Asia/Kabul |
| Asia/Kamchatka |
| Asia/Karachi |
| Asia/Kathmandu |
| Asia/Khandyga |
| Asia/Kolkata |
| Asia/Krasnoyarsk |
| Asia/Kuala_Lumpur |
| Asia/Kuching |
| Asia/Kuwait |
| Asia/Macau |
| Asia/Magadan |
| Asia/Makassar |
| Asia/Manila |
| Asia/Muscat |
| Asia/Nicosia |
| Asia/Novokuznetsk |
| Asia/Novosibirsk |
| Asia/Omsk |
| Asia/Oral |
| Asia/Phnom_Penh |
| Asia/Pontianak |
| Asia/Pyongyang |
| Asia/Qatar |
| Asia/Qostanay |
| Asia/Qyzylorda |
| Asia/Riyadh |
| Asia/Sakhalin |
| Asia/Samarkand |
| Asia/Seoul |
| Asia/Shanghai |
| Asia/Singapore |
| Asia/Srednekolymsk |
| Asia/Taipei |
| Asia/Tashkent |
| Asia/Tbilisi |
| Asia/Tehran |
| Asia/Thimphu |
| Asia/Tokyo |
| Asia/Tomsk |
| Asia/Ulaanbaatar |
| Asia/Urumqi |
| Asia/Ust-Nera |
| Asia/Vientiane |
| Asia/Vladivostok |
| Asia/Yakutsk |
| Asia/Yangon |
| Asia/Yekaterinburg |
| Asia/Yerevan |
| Atlantic/Azores |
| Atlantic/Bermuda |
| Atlantic/Canary |
| Atlantic/Cape_Verde |
| Atlantic/Faroe |
| Atlantic/Madeira |
| Atlantic/Reykjavik |
| Atlantic/South_Georgia |
| Atlantic/St_Helena |
| Atlantic/Stanley |
| Australia/Adelaide |
| Australia/Brisbane |
| Australia/Broken_Hill |
| Australia/Darwin |
| Australia/Eucla |
| Australia/Hobart |
| Australia/Lindeman |
| Australia/Lord_Howe |
| Australia/Melbourne |
| Australia/Perth |
| Australia/Sydney |
| Europe/Amsterdam |
| Europe/Andorra |
| Europe/Astrakhan |
| Europe/Athens |
| Europe/Belgrade |
| Europe/Berlin |
| Europe/Bratislava |
| Europe/Brussels |
| Europe/Bucharest |
| Europe/Budapest |
| Europe/Busingen |
| Europe/Chisinau |
| Europe/Copenhagen |
| Europe/Dublin |
| Europe/Gibraltar |
| Europe/Guernsey |
| Europe/Helsinki |
| Europe/Isle_of_Man |
| Europe/Istanbul |
| Europe/Jersey |
| Europe/Kaliningrad |
| Europe/Kirov |
| Europe/Kyiv |
| Europe/Lisbon |
| Europe/Ljubljana |
| Europe/London |
| Europe/Luxembourg |
| Europe/Madrid |
| Europe/Malta |
| Europe/Mariehamn |
| Europe/Minsk |
| Europe/Monaco |
| Europe/Moscow |
| Europe/Oslo |
| Europe/Paris |
| Europe/Podgorica |
| Europe/Prague |
| Europe/Riga |
| Europe/Rome |
| Europe/Samara |
| Europe/San_Marino |
| Europe/Sarajevo |
| Europe/Saratov |
| Europe/Simferopol |
| Europe/Skopje |
| Europe/Sofia |
| Europe/Stockholm |
| Europe/Tallinn |
| Europe/Tirane |
| Europe/Ulyanovsk |
| Europe/Vaduz |
| Europe/Vatican |
| Europe/Vienna |
| Europe/Vilnius |
| Europe/Volgograd |
| Europe/Warsaw |
| Europe/Zagreb |
| Europe/Zurich |
| Indian/Antananarivo |
| Indian/Chagos |
| Indian/Christmas |
| Indian/Cocos |
| Indian/Comoro |
| Indian/Kerguelen |
| Indian/Mahe |
| Indian/Maldives |
| Indian/Mauritius |
| Indian/Mayotte |
| Indian/Reunion |
| Pacific/Apia |
| Pacific/Auckland |
| Pacific/Bougainville |
| Pacific/Chatham |
| Pacific/Chuuk |
| Pacific/Easter |
| Pacific/Efate |
| Pacific/Fakaofo |
| Pacific/Fiji |
| Pacific/Funafuti |
| Pacific/Galapagos |
| Pacific/Gambier |
| Pacific/Guadalcanal |
| Pacific/Guam |
| Pacific/Honolulu |
| Pacific/Kanton |
| Pacific/Kiritimati |
| Pacific/Kosrae |
| Pacific/Kwajalein |
| Pacific/Majuro |
| Pacific/Marquesas |
| Pacific/Midway |
| Pacific/Nauru |
| Pacific/Niue |
| Pacific/Norfolk |
| Pacific/Noumea |
| Pacific/Pago_Pago |
| Pacific/Palau |
| Pacific/Pitcairn |
| Pacific/Pohnpei |
| Pacific/Port_Moresby |
| Pacific/Rarotonga |
| Pacific/Saipan |
| Pacific/Tahiti |
| Pacific/Tarawa |
| Pacific/Tongatapu |
| Pacific/Wake |
| Pacific/Wallis |
authorization
Specifies the authorization token to include with the API request, typically used to access protected resources.
This should be a string encoded in Base64 and passed as the value of the Authorization header.
Example: authorization=<base64-encoded-token>
Note: Ensure the token is properly encoded to avoid authentication errors. Common formats include Basic Auth (username:password) or Bearer tokens, depending on the target service.
attachment_name
This parameter specifies the name of the attachment for the result. It should be a string without the extension. The extension will be computed from the response. This can be useful for identifying the screenshot in a list of attachments. Example: attachment_name=screenshot.
user_agent
This parameter specifies the user agent string to use for the request. It should be a string. This allows for simulating different browsers or devices. Example: user_agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3.
cookies
This parameter allows for specifying cookies to include in the request. It should be an array of strings. This can be useful for maintaining session state. Example: cookies=session_id=abc123&cookies=user_id=xyz789.
headers
This parameter allows for specifying additional headers to include in the request. It should be an array of strings. This can be useful for passing custom headers. Example: headers=X-Custom-Header:value.
ip_location
This parameter specifies the IP location to simulate. It should be a string that matches one of the supported values.
Example:
ip_location=us
Supported values:
| Country Code | Country |
|---|---|
| us | United States |
| cn | China |
| eu | European Union (random EU country) |
| ca | Canada |
| mx | Mexico |
| gb | United Kingdom |
| de | Germany |
| fr | France |
| ch | Switzerland |
| in | India |
| jp | Japan |
| kr | South Korea |
| ru | Russia |
| br | Brazil |
| au | Australia |
bypass_csp
This parameter indicates whether to bypass Content Security Policy during the capture. It is a boolean value with a default of false. This can be useful for testing pages with strict CSP. Example: bypass_csp=true.
proxy
This parameter specifies a proxy server to use for the request. It should be a string in URI format. This can be useful for routing requests through a specific server. Example: proxy=http://proxy.example.com:8080.
Wait
This section describes the parameters that can be used to control the timing of the capture process.
delay
This parameter sets a delay in seconds before taking the capture. It must be an integer between 0 and 30, with a default of 0. This can help ensure that the page is fully loaded before capturing. Example: delay=5.
timeout
This parameter sets a timeout in seconds for the request. It must be an integer between 0 and 30, with a default of 30. This can help prevent long waits for unresponsive pages. Example: timeout=10.
wait_until
This parameter specifies the events to wait for before taking the capture.
It should be an array of strings that match one of the supported events.
Default is domcontentloaded.
Example: wait_until=load&wait_until=networkidle0
| Event | Description |
|---|---|
load | Waits for the load event to fire (all resources including images and scripts). |
domcontentloaded | Waits for the DOMContentLoaded event (when the initial HTML document is fully loaded and parsed). |
networkidle0 | Waits until there are no more than 0 network connections for at least 500 ms. |
networkidle2 | Waits until there are no more than 2 network connections for at least 500 ms. |
Metadata
The metadata parameters allow you to include additional information in the capture request. This can be useful for debugging, analysis, or simply to provide more context about the captured content.
metadata_icon
This parameter indicates whether to include the website’s icon (favicon) in the metadata. It is a boolean value with a default of false. Example: metadata_icon=true.
If enabled, the response headers will include: X-Screenshotmax-Metadata-Icon — the URL path to the favicon of the target webpage.
metadata_fonts
This parameter indicates whether to include font information in the metadata. It is a boolean value with a default of false. This can be useful for analyzing the fonts used on the webpage. Example: metadata_fonts=true.
If enabled, the response headers will include: X-Screenshotmax-Metadata-Fonts — a comma-separated list of fonts used on the page.
metadata_title
This parameter indicates whether to include the page title in the metadata. It is a boolean value with a default of false. Example: metadata_title=true.
If enabled, the response headers will include: X-Screenshotmax-Metadata-Title — the <title> of the target webpage.
metadata_status
This parameter indicates whether to include the HTTP status in the metadata. It is a boolean value with a default of false. This can be useful for understanding the response status of the request. Example: metadata_status=true.
If enabled, the response headers will include: X-Screenshotmax-Metadata-Status — the HTTP status code of the response.
metadata_headers
This parameter indicates whether to include the response headers in the metadata. It is a boolean value with a default of false. This can help in analyzing the headers returned by the server. Example: metadata_headers=true.
If enabled, the response headers will include: X-Screenshotmax-Metadata-Headers — a JSON string of all response headers from the target webpage.
metadata_hash
This parameter indicates whether to include a hash of the captured content in the metadata. It is a boolean value with a default of false. Example: metadata_hash=true.
If enabled, the response headers will include: X-Screenshotmax-Metadata-Hash — a SHA-256 hash of the webpage content, useful for change detection.
Caching
This section outlines the parameters available to configure caching behavior for content responses in API requests. Captured content can be stored in the cache for a specified duration, enabling faster retrieval of previously processed results. This helps reduce load times and improve performance for frequently accessed content.
Cached content is accessible via a URL in the following format: https://cache.screenshotmax.com/{hash}.{ext}
In the response headers, the key X-Screenshotmax-Cache-Url provides the direct URL to the cached version of the content.
cache
This parameter indicates whether to enable caching for the result. It is a boolean value with a default of false. Example: cache=true.
cache_ttl
This parameter sets the time-to-live for cached result in seconds. It must be an integer between 1 and 2,592,000 (30 days), with a default of 604,800 (7 days). This controls how long cached results are kept. Example: cache_ttl=86400.
Async and Webhook
This section outlines the parameters used for asynchronous processing and webhook notifications in API requests.
async
This parameter indicates whether the request should be processed asynchronously. It is a boolean value with a default of false. This can be useful for handling long-running requests without blocking. Example: async=true.
webhook_url
This parameter specifies a webhook URL to send notifications to when the request is completed. It should be a string in URI format.
The webhook URL muste support POST requests and be publicly accessible. Example: webhook_url=https://example.com/webhook.
webhook_signed
This parameter indicates whether the webhook should be signed for security. It is a boolean value with a default of true. This can help ensure that notifications are from a trusted source. Example: webhook_signed=false.
The signature is a SHA-256 hash of the request body combined with your secret key. It ensures the authenticity of the notification and protects against tampering. For details on how to verify the signature, refer to the signed requests documentation.