How to Capture Cookie-Protected Pages with a Screenshot API

To capture a cookie-protected page, send the screenshot API a valid session cookie for the target site in that provider’s documented format. Make sure the cookie’s domain and path cover the requested URL, wait for the protected content to render, and inspect the returned image: a successful API response can still show a login page or an error.

Use this workflow only for pages you are authorized to access. A screenshot API cannot infer your browser session from a URL, and a cookie does not override a site’s access policy or bot defenses.

1. Confirm the page’s authentication method

First determine what the target expects. A browser session usually uses cookies; other pages may use HTTP Basic Auth or an authorization header. These credentials are separate from the token used to authenticate your request to the screenshot provider.

Target authentication	What to send	Check
Browser session	The current session cookie or cookies	Cookie name, value, domain, path, expiry, and provider-specific representation
HTTP Basic Auth	Username and password in the provider’s Basic Auth option	The target is protected by Basic Auth, rather than a form-based login
Bearer token or custom header	The target-required header, such as `Authorization`	The header is sent to the target page in the format it expects

Use the minimum credential needed. Treat session cookies, passwords, and tokens as secrets: do not put live values in source control, public examples, shared URLs, or logs. The provider’s API key authenticates your capture request; it is not the target site’s login credential.

Cookies are scoped to a host or domain and a path. A cookie for a different host or a narrower path may not be sent to the protected URL. Some services accept structured cookie objects; others expect a serialized cookie string with attributes. Use the screenshot API’s own documented shape instead of copying another provider’s syntax.

For example, Cloudflare Browser Run documents a JSON cookie array with name, value, domain, and path. ScreenshotOne documents a formatted cookie string that can include domain, path, HttpOnly, Secure, and SameSite attributes. Those formats are provider-specific. See the Cloudflare Browser Run documentation and ScreenshotOne’s guide to pages behind a login.

{
  "url": "https://example.com/protected-page",
  "cookies": [
    {
      "name": "session_id",
      "value": "YOUR_SESSION_COOKIE",
      "domain": "example.com",
      "path": "/"
    }
  ]
}

This is Cloudflare’s documented cookie-object shape, not a universal screenshot API schema. Replace the placeholder with a valid credential obtained through an authorized flow. Do not reuse sample credential values from documentation.

3. Send the capture request and wait for the page

For Cloudflare Browser Run, the documented screenshot endpoint accepts a POST request with the target URL and cookies. Authenticate that API request with an API token that has the documented Browser Rendering permission. The target-site cookie goes in the request body; the Cloudflare API token goes in the request authorization header.

curl -X POST \
  "https://api.cloudflare.com/client/v4/accounts/ACCOUNT_ID/browser-run/screenshot" \
  -H "Authorization: Bearer CLOUDFLARE_API_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://example.com/protected-page",
    "cookies": [
      {
        "name": "session_id",
        "value": "YOUR_SESSION_COOKIE",
        "domain": "example.com",
        "path": "/"
      }
    ]
  }' \
  --output protected-page.png

Replace the account ID, API token, cookie, and target URL. Store real credentials in a secret manager or environment variables in your application. If you use another provider, adapt the request to its endpoint, authentication, output handling, and cookie format.

For a page that renders content with JavaScript, a navigation-complete event may happen before the page is useful. Wait for network idle or, preferably when available, a stable selector that appears only after the authenticated content loads. A selector can be more reliable when the app keeps unrelated network connections open. Cloudflare documents gotoOptions.waitUntil values such as networkidle0 and networkidle2, as well as waiting for a selector. See its Browser Rendering documentation.

4. Verify the returned image

Open the image and check that it contains the expected account or report. A successful HTTP response only tells you that the screenshot request returned; it does not prove that the target authenticated the session or finished rendering the right content.

If you see a login form, confirm cookie validity, domain, path, expiry, and the API’s expected encoding.
If you see a partial or blank app, wait for a known content selector or adjust the render wait.
If the response contains an error page, check target access policy and whether the API’s servers can reach the site.
If the page changes between captures, check whether the session expires or requires additional cookies.

5. Choose the right capture approach

Session cookies

Use cookies when the target’s authorized login flow establishes a browser session. Some services let you submit cookies directly; others require your own code to sign in and obtain them. The documentation reviewed here does not define one universal login automation procedure.

HTTP Basic Auth

For a target protected by HTTP Basic Auth, Cloudflare Browser Run documents an authenticate object containing a username and password. Use this only when Basic Auth is actually the site’s mechanism; it will not substitute for a form-based session cookie.

{
  "url": "https://example.com/private-report",
  "authenticate": {
    "username": "YOUR_USERNAME",
    "password": "YOUR_PASSWORD"
  }
}

Authorization or custom headers

If the target expects a bearer token or another header, use the provider’s documented option for adding headers. Cloudflare documents setExtraHTTPHeaders; ScreenshotOne documents custom headers, including an Authorization header. Confirm whether the provider applies the header to the target navigation and any relevant requests.

{
  "url": "https://example.com/private-report",
  "setExtraHTTPHeaders": {
    "Authorization": "Bearer YOUR_TARGET_TOKEN"
  }
}

Allowlisted access for a site you control

For a site you operate, a provider may offer a documented way to allow its capture servers through your firewall. ScreenshotOne describes this as an option for owned sites. It is not a general way to access a third party’s protected page; follow the site’s approved integration path.

Rendered content and screenshot together

When a workflow needs both a visual capture and structural output, Cloudflare’s /snapshot endpoint can return rendered content and a screenshot in one call. Check its current documentation for the endpoint’s request and response details.

6. Provider examples and portability

Authentication fields are not portable just because two services both take screenshots. Verify the endpoint, API authentication, target credential format, wait behavior, response type, and output options before switching. Cloudflare’s examples use a cookie array; ScreenshotOne’s guide shows its own serialized cookie syntax and URL-encoding requirements. Follow the provider’s current documentation for exact request construction.

ScreenshotNeo accepts custom cookies, headers, user agents, and Authorization, along with selector waits, a delay, or network-idle waiting. Its API also supports full-page capture, element capture, and PNG, JPEG, WebP, or PDF output. See the ScreenshotNeo API documentation for parameter names and request details.

7. Troubleshooting

Symptom	Likely cause	Fix
Capture shows a login page	Cookie is expired, belongs to another account, has the wrong scope, or was serialized incorrectly	Obtain a fresh authorized session cookie; check its domain and path; use the provider’s exact cookie format; inspect the image again
Capture shows an incomplete or blank app	The screenshot was taken before JavaScript finished rendering	Wait for a stable content selector or network idle; choose a selector specific to authenticated content
Provider rejects the request	Wrong endpoint, request method, API token permission, JSON shape, or encoding	Compare the request with the provider’s current API documentation; separate provider API credentials from target credentials
Cookie works in a browser but not in the capture	Wrong host/path, omitted related cookie, expired session, or target behavior that depends on browser state	Check the full authorized session requirements and cookie attributes; confirm the capture request reaches the expected host
Target blocks automation	The site identifies automated browser traffic or disallows the access path	Use an integration the site permits. Changing the user agent does not guarantee access; Cloudflare says Browser Run requests remain identifiable as bot traffic
Image is an error page despite an image response	The target returned an error page that the screenshot service rendered successfully	Inspect the image content, check target availability and access rules, then correct credentials or the approved access method
Secret appears in logs or history	Credential was embedded in a URL, command history, or verbose request log	Remove exposure where possible, rotate the affected credential, and move secrets to protected configuration

8. Performance, reliability, and cost

Wait only as long as needed. A known selector can avoid waiting on persistent background traffic; network idle is useful when the page’s content depends on several requests.
Keep sessions fresh. Expired sessions create captures of login pages, so establish a renewal process appropriate to the site’s permitted authentication flow.
Check the output. Validate that important page content is present when a capture feeds QA, reporting, or another automated workflow.
Account for provider-specific billing. The research sources do not provide comparable costs or a shared billing rule. Check the provider’s pricing and billing documentation for failed loads, retries, and output formats.
Limit credential exposure. Avoid printing cookies or authorization headers in application logs and keep access scoped to the minimum required.

Or skip the browser setup

ScreenshotNeo can receive a URL and authorized cookies in one API call, without building and maintaining your own browser capture setup. Cookie banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and whether it was billed. Its MCP server lets AI agents using Claude, Cursor, or another MCP client take screenshots, inspect page information, and capture PDFs.

1,000 screenshots a month are free with no card. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan. See the API docs for cookie and request options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com/protected-page \
  --data-urlencode cookies='session_id=YOUR_SESSION_COOKIE' \
  -o shot.webp

Pass the cookie in the documented format for the target and keep the API key and session value private. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Can a screenshot API use the cookies already in my browser?

Not from the page URL alone. You need to provide credentials through an authorized, provider-supported workflow.

Only if you are authorized to access the page and the site permits the capture method. A valid cookie does not grant permission to bypass site policy.

Does changing the user agent make a blocked capture work?

Not necessarily. Cloudflare states that Browser Run traffic remains identifiable as bot traffic, even when the user agent is changed.

How do I know the capture is authenticated?

Inspect the image for the expected protected content. An image response by itself does not confirm a successful login.