How to capture a password-protected web page with ScreenshotMachine

To capture an authorized password-protected page with ScreenshotMachine, first sign in through the website’s normal login process, obtain a valid session cookie, then pass that cookie in ScreenshotMachine’s cookies parameter. The API documentation describes cookies as the relevant input for a cookie-backed session. It does not document sending a destination-site username and password or logging in through arbitrary forms.

Keep both the ScreenshotMachine API key and the session cookie private. Only capture pages you are authorized to access, and check the destination site’s rules before automating captures.

How the authenticated capture works

Sign in to the destination website through its normal, authorized flow.
Obtain a still-valid session cookie for the page’s host and path using the site’s supported developer tools or authentication process.
Build the full page URL, including any query parameters the page needs.
Percent-encode the cookie string and send it with your ScreenshotMachine API key and target URL.
Inspect the returned image and response header. If the page still shows a login screen or an error image, troubleshoot the session and request as described below.

A cookie can represent an already authenticated session; it is not the same as the ScreenshotMachine API key. The API reference also describes an optional hash for protecting public-page API calls. That hash is not a credential for the protected destination page.

Build the ScreenshotMachine request

The request needs the destination url, your ScreenshotMachine key, and the encoded cookies value. The API accepts semicolon-separated cookie pairs such as name1=value1;name2=value2. Encode the whole string: the example becomes name1%3Dvalue1%3Bname2%3Dvalue2.

Use a URL encoder rather than hand-encoding real cookie values. Cookie values and destination URLs can contain reserved characters; encoding avoids changing their meaning in the query string.

cURL

curl -G 'https://api.screenshotmachine.com' \
  --data-urlencode 'key=YOUR_SCREENSHOTMACHINE_KEY' \
  --data-urlencode 'url=https://example.com/account/reports' \
  --data-urlencode 'cookies=sessionid=YOUR_SESSION_COOKIE' \
  --data-urlencode 'dimension=1024x768' \
  --data-urlencode 'device=desktop' \
  --data-urlencode 'format=png' \
  --data-urlencode 'cacheLimit=0' \
  -o protected-page.png

--data-urlencode encodes the cookie parameter, including its equals sign. Replace the placeholders locally; do not commit a real API key or cookie to source control or paste them into a public terminal transcript.

Python

from urllib.parse import urlencode
import requests

endpoint = "https://api.screenshotmachine.com"
params = {
    "key": "YOUR_SCREENSHOTMACHINE_KEY",
    "url": "https://example.com/account/reports",
    "cookies": "sessionid=YOUR_SESSION_COOKIE",
    "dimension": "1024x768",
    "device": "desktop",
    "format": "png",
    "cacheLimit": 0,
}

response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()

with open("protected-page.png", "wb") as image_file:
    image_file.write(response.content)

print("Saved protected-page.png")
print("ScreenshotMachine response:", response.headers.get("X-Screenshotmachine-Response"))

The HTTP status alone may not identify a capture failure: the API documentation says invalid or incomplete requests can return an error image. Check the provider response header and inspect the downloaded file before treating it as a successful screenshot.

Node.js

const params = new URLSearchParams({
  key: 'YOUR_SCREENSHOTMACHINE_KEY',
  url: 'https://example.com/account/reports',
  cookies: 'sessionid=YOUR_SESSION_COOKIE',
  dimension: '1024x768',
  device: 'desktop',
  format: 'png',
  cacheLimit: '0',
});

const response = await fetch(`https://api.screenshotmachine.com?${params}`);
if (!response.ok) {
  throw new Error(`ScreenshotMachine HTTP error: ${response.status}`);
}

const bytes = Buffer.from(await response.arrayBuffer());
const fs = await import('node:fs/promises');
await fs.writeFile('protected-page.png', bytes);
console.log('Saved protected-page.png');
console.log('ScreenshotMachine response:', response.headers.get('X-Screenshotmachine-Response'));

URLSearchParams encodes query values. Use an appropriate request timeout in production and verify that the result is an image rather than an API error image.

Choose capture settings for the page

ScreenshotMachine documents settings for viewport dimensions, device, output format, delay, full-page height, and cache behavior. The right settings depend on the page after the authenticated session is accepted.

Setting	Use it for	Notes
`dimension`	Setting the viewport size	Choose dimensions suited to the content you need to inspect.
`device`	Desktop, phone, or tablet rendering	The viewport can change responsive layout and which elements appear.
`format`	Choosing JPG, PNG, or GIF output	Match the requested format to your downstream use.
`delay`	Waiting for slow assets or animations	A longer delay may help a page finish rendering, but increases capture time.
Full-page height	Capturing a long document beyond the initial viewport	Long pages can take longer to render and capture.
`cacheLimit`	Controlling screenshot freshness	Set it to `0` when the capture must be fresh. The API reference describes cache ages in days.

For a frequently changing dashboard, request a fresh capture when current data matters. For repeated retrieval of an unchanged page, cache reuse can avoid unnecessary work; ScreenshotMachine’s pricing page says cached downloads are not billed and screenshots are retained for 14 days. Confirm current terms and pricing on the provider’s site before relying on them.

Protect cookies and API credentials

Use a dedicated, least-privilege account or session when the target service supports one.
Keep the ScreenshotMachine key and target session cookie in a secret store or environment configuration, not in checked-in code.
Avoid logging full request URLs: query strings can contain both credentials.
Do not expose a cookie-bearing request in a browser address bar, public issue, analytics event, or shared screenshot of a terminal.
Revoke or rotate credentials if they are disclosed, and use short-lived sessions where available.
Capture only pages you are permitted to access. ScreenshotMachine’s terms restrict unlawful or harmful use and systematic automated collection without express written consent.

The cookie must remain usable by the capture request. A cookie copied from a browser is sensitive authentication material, even if it looks like an opaque random string.

Troubleshooting

Symptom	Likely cause	What to check
An error image appears	The API documents error images for invalid or incomplete requests.	Inspect `X-Screenshotmachine-Response`, confirm the key and required parameters, and check that the target URL is valid.
`invalid_url` or a page that behaves like a 401	The documentation lists an authorization-required 401 as a possible reason for `invalid_url`.	Confirm the URL and that the session cookie is valid, encoded, and applicable to the target host and path.
The result is the login page	The cookie may have expired, may not cover the requested host/path, or the site may require additional session state.	Obtain a fresh cookie through the normal login flow and verify the target’s redirect behavior. Some login methods may not be represented by one cookie.
The request URL is malformed	Reserved characters in the destination URL or cookie string were not encoded correctly.	Pass parameters through a URL encoder, such as `--data-urlencode`, Python’s `params`, or Node’s `URLSearchParams`.
The screenshot is stale	A cached result may be reused.	Set `cacheLimit=0` when a fresh image is required.
Content is missing or still loading	The page may need more rendering time, particularly when assets or animations load late.	Increase `delay` and consider whether a full-page capture is making the operation longer.
Authentication still fails with a fresh cookie	The destination may use a flow or state the documented cookie parameter does not cover.	Do not assume direct username/password form login or HTTP Basic Auth support. Check the target’s supported authentication method and ask ScreenshotMachine about the specific case.

These checks follow the documented cookie input and 401/error-image behavior. They are troubleshooting possibilities, not a guarantee that every protected site or login mechanism will work.

Performance, reliability, and cost

Capture time depends on rendering, page length, and any configured delay. Increasing delay can allow assets or animations to finish but also makes each request take longer. Full-page captures of long pages can take longer than a viewport capture. For reliable jobs, use a sensible client timeout, record the provider response header, and treat an error image or unexpected login page as a failed capture rather than a valid result.

Set cacheLimit=0 for freshness-sensitive pages. ScreenshotMachine’s pricing information says screenshots are cached for 14 days and cached downloads are not billed. Its published plan allowances and prices can change; the currently researched page lists a free allowance of 100 fresh screenshots per month, Basic at €9/month for 2,500, Pro at €59/month for 20,000, and Enterprise at €99/month for 50,000. Check the ScreenshotMachine pricing page for current amounts, overage terms, and availability before budgeting.

Use automated capture only within the destination site’s access rules and your authorization. ScreenshotMachine’s terms prohibit systematic or automated data collection on or in relation to its service without express written consent, in addition to restrictions on unlawful or harmful use. Review the ScreenshotMachine terms for the applicable conditions.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. For cookie-backed target access, pass the authorized session cookie as a custom header if the target accepts it; the simple call below demonstrates the API request shape for a public URL and does not claim to log into a protected site. See the ScreenshotNeo API documentation for its request options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Can I give ScreenshotMachine my website username and password?

The reviewed API reference documents a cookies parameter, not a username/password field or arbitrary form-login workflow. Authenticate through the destination site’s normal process and use an authorized session cookie if the site’s flow supports it.

Does the API key authenticate me to the protected website?

No. The ScreenshotMachine key authorizes your API request to ScreenshotMachine. The destination-site session cookie is separate.

Not necessarily. Cookie scope, expiry, redirects, and extra authentication state vary by site. The API documentation does not promise support for every protected-page authentication scheme.

What if the site requires a one-time code or a security key?

The documented cookie parameter does not describe completing those login steps. Use only a session obtained through an authorized flow, and confirm the specific target’s requirements with the provider.

Can I use this to capture pages I cannot access?

No. The workflow is for pages you are authorized to access. It is not a method for bypassing access controls.

Sources

ScreenshotMachine API documentation — request parameters, cookies, output options, cache behavior, and error responses.
ScreenshotMachine pricing — published plan allowances, prices, and caching terms.
ScreenshotMachine terms — restrictions on unlawful use and systematic automated collection.