How to Add Authentication Cookies to Apify Website Screenshot Requests

To capture an authenticated page with Apify’s josh99smith/website-screenshot-api Actor, pass the target site’s session cookies in the Actor input’s cookies array. The Actor documentation says it sets these Playwright cookies before navigating to the requested page. Keep the website cookies separate from your Apify API token: the cookies authenticate the browser session at the target site, while the token authorizes your request to Apify.

This guide covers the documented input for that Actor. Other Apify screenshot Actors can use different schemas, so confirm the input format on the page for the Actor you run.

1. Build the cookie input

Each cookie object in the Actor’s example includes a name, value, domain, and path. Replace the placeholders with values for a session you are authorized to use:

{
  "urls": ["https://www.example.com/account"],
  "cookies": [
    {
      "name": "session",
      "value": "<YOUR_SESSION_COOKIE>",
      "domain": ".example.com",
      "path": "/"
    }
  ]
}

The domain and path must match the target URL’s cookie scope. For example, a cookie scoped to a different host or a narrower path may not apply to https://www.example.com/account. Do not publish a real session value in source code, documentation, tickets, or logs. Treat it as a credential.

2. Run the Actor from the Apify Console

1. Open the website-screenshot-api Actor page and start the Actor.
2. Set the screenshot URL to the authenticated page you need.
3. In Advanced options, provide the cookie objects in the Cookies setting, or edit the input JSON to include the cookies property shown above.
4. Run the Actor and inspect the result record and screenshot. A completed run does not by itself prove that the site displayed authenticated content.

The Actor page describes additional controls such as load waiting, waitForSelector, delay, scrolling, and retries. Use them when the authenticated page renders content after initial navigation. They can help with timing; they do not make an expired session valid or bypass a login challenge.

3. Call the Actor through the REST API

For a REST run, send the Actor input as JSON to the Actor’s run endpoint and authenticate to Apify with a bearer token. The precise endpoint form and available run options are documented by Apify; use the current endpoint shown in the Actor API examples and Apify API documentation.

export APIFY_TOKEN='YOUR_APIFY_API_TOKEN'

curl -X POST \
  'https://api.apify.com/v2/acts/josh99smith~website-screenshot-api/runs' \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "urls": ["https://www.example.com/account"],
    "cookies": [
      {
        "name": "session",
        "value": "<YOUR_SESSION_COOKIE>",
        "domain": ".example.com",
        "path": "/"
      }
    ]
  }'

Keep APIFY_TOKEN in a protected environment setting rather than committing it to a repository. Likewise, supply the session cookie from a protected secret store or runtime configuration. Do not print either secret while debugging. The API token belongs in the Apify authorization header, never in the target website’s cookies array.

4. Call the Actor with the Apify JavaScript client

The Actor page documents calling the Actor with ApifyClient and passing the Actor input to call(). Install the client in your project using the package installation instructions in Apify’s documentation, then run code like this in an environment where APIFY_TOKEN and SESSION_COOKIE are set:

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('josh99smith/website-screenshot-api').call({
  urls: ['https://www.example.com/account'],
  cookies: [
    {
      name: 'session',
      value: process.env.SESSION_COOKIE,
      domain: '.example.com',
      path: '/',
    },
  ],
});

console.log(`Run ID: ${run.id}`);
console.log(`Run status: ${run.status}`);

This example starts the run and prints its ID and status. Check the Actor’s current documentation for how to retrieve its output records and screenshot URLs. Avoid logging the input object because it contains a live session secret.

Cookie details and edge cases

• Cookie scope: Set the domain and path that apply to the requested URL. A cookie for a different subdomain or path may be omitted by the browser context.
• Session freshness: The Actor sets the supplied cookie before navigation, but cannot extend, refresh, or restore a session that the website has expired or revoked.
• Multiple cookies: The input is an array. Supply each relevant cookie as an object in that array, following the Actor’s documented Playwright cookie format.
• Additional login requirements: A site may require more than one cookie or another authentication step. The Actor documentation does not guarantee compatibility with every login flow.
• Cookie banners: The Actor’s hideCookieBanners option visually hides consent banners with CSS; the documentation says it does not accept consent on your behalf. Hiding a banner does not authenticate the page.
• Actor-specific schema: This cookie format is for josh99smith/website-screenshot-api. Check the schema before using another Actor.

Troubleshooting

Symptom	Likely cause	What to check
Apify rejects the request or the Actor does not start	The Apify token is missing or invalid, or the request shape is wrong.	Check the bearer token and endpoint against Apify’s current API docs. This is separate from the website session cookie.
The screenshot shows a login page	The cookie may be expired, revoked, scoped to another domain or path, or insufficient for that login flow.	Confirm the current cookie name, value, domain, and path for the exact target URL. Check whether the site requires additional authentication.
The page is authenticated but content is missing	Protected content may render after navigation or after a page-specific condition.	Review the Actor’s load-waiting settings, delay, scrolling, and waitForSelector options. These affect capture timing, not authentication.
The cookie banner remains visible	A consent banner is separate from login cookies, or the Actor’s visual-hiding option is not enabled or does not cover that banner.	Check the Actor’s hideCookieBanners setting. Hiding is visual only and does not submit consent.
The run reports success, but the image is wrong	A successful run does not necessarily mean the target rendered the expected authenticated state.	Inspect the output record, status, warnings, and screenshot itself. Verify the requested URL and cookie scope.
A cookie works in one environment but not another	The copied value may have changed, expired, or been exposed and invalidated; runtime settings may also differ.	Use a current authorized session and provide it through protected runtime configuration. Rotate any value that was exposed.

Security, reliability, and cost considerations

Use only sessions you are authorized to use. Keep cookie values and Apify tokens out of source control and application logs, and rotate a session value if it has been exposed. The Actor page says its cookies are never logged, and says its extraHeaders are sent only to the page’s own domain and subdomains and are never logged. Treat those as statements about the Actor’s documented behavior, not a broader guarantee about the target site, Apify platform storage, or other logging outside that Actor behavior.

For reliability, verify the captured page rather than relying only on the run status. Session expiry, domain scope, additional authentication steps, and asynchronous page rendering can all affect the result. For cost, check the current Actor plan and Apify run pricing before scheduling repeated or batch captures; the reviewed Actor documentation does not establish a universal cost for a particular capture.

Or skip the browser setup

ScreenshotNeo is a website screenshot API: send one GET request with a URL to receive a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation for 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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await Bun.write('shot.webp', bytes);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. An MCP server lets Claude, Cursor, and other MCP clients use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up for ScreenshotNeo’s free 1,000 screenshots a month, with no card required.

FAQ

Does a successful Actor run prove the cookie worked?

No. Inspect the screenshot and output record to confirm that the page shows the expected account state.

Can I use a cookie copied from a browser session?

Use it only if you are authorized to use that session, and keep the value secret. A copied cookie may expire or be revoked.

Does hiding a consent banner log the user in?

No. Banner hiding is a visual operation; authentication depends on valid target-site session cookies and the site’s own login rules.

Can I reuse this input with every Apify screenshot Actor?

No. Input fields vary by Actor. Confirm the schema for the Actor you intend to run.