Puppeteer Cookie Data: Fields and Usage

CookieData is the object Puppeteer uses with the browser-level cookie API. It describes a cookie’s name and value, scope, lifetime, security flags, same-site setting, and optional browser-specific metadata. Choose the browser context that should own the cookie before setting it: browser convenience methods use the default context, while a BrowserContext lets you keep cookie storage isolated. Use CookieParam when setting cookies through the page-level API; it has an optional url field that can determine cookie defaults.

This guide follows the Puppeteer 25.12.0 API reference. Check the documentation for the version installed in your project if signatures or browser support differ.

1. CookieData fields

The CookieData reference describes these properties:

Field	Meaning	Notes
name	Cookie name.	Required.
value	Cookie value.	Required.
domain	Domain scope for the cookie.	Use the intended host or valid parent domain for the target site.
path	Path scope for the cookie.	Controls which paths receive the cookie.
expires	Expiration date.	Optional. If omitted, Puppeteer documents the cookie as a session cookie.
httpOnly	Whether the cookie is marked HttpOnly.	Optional boolean.
secure	Whether the cookie is marked Secure.	Optional boolean.
sameSite	Same-site policy.	Optional CookieSameSite value. Consult Puppeteer’s versioned type documentation for accepted values.
partitionKey	Partition key for a partitioned cookie.	Browser-specific interpretation: Puppeteer documents Chrome matching the top-level site where the cookie is available, and Firefox matching the source origin in the partition key.
priority	Cookie priority metadata.	Documented as supported only in Chrome.
sourceScheme	Cookie source scheme metadata.	Documented as supported only in Chrome.

The reference is the authority for accepted value types and browser support. In particular, don’t assume optional metadata is portable across browsers.

2. CookieData vs CookieParam

These names refer to parameter objects for different API levels, so they are not interchangeable in every call.

Type	API level	Distinguishing detail
CookieData	Browser-level cookies API	Describes cookie fields such as name, value, domain, and path.
CookieParam	Page-level cookie-setting API	Includes optional url; the URL can affect default domain, path, and source scheme.

Use the object type documented for the method you call. The CookieParam reference explains the URL-related defaults. If you already know the cookie scope, specify the appropriate fields explicitly rather than depending on an implicit default.

3. Set a cookie with Puppeteer

Install Puppeteer in a Node.js project, then save this as cookie.mjs. This example creates a named browser context so the cookie is scoped to that context’s isolated storage.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({ headless: true });
const context = await browser.createBrowserContext();

try {
  const page = await context.newPage();
  await page.goto('https://example.com/', { waitUntil: 'domcontentloaded' });

  await context.setCookie({
    name: 'session_hint',
    value: 'demo-value',
    domain: 'example.com',
    path: '/',
    httpOnly: true,
    secure: true,
    sameSite: 'Lax',
  });

  console.log(await context.cookies('https://example.com/'));
} finally {
  await context.close();
  await browser.close();
}

Replace the example cookie and host with values appropriate for your application. Do not place real session secrets in source code or logs. The context is closed in finally so browser resources are released even if navigation or cookie operations fail.

4. Choose the cookie context and inspect state

A BrowserContext represents an individual user context. Its storage, including cookies and local storage, is isolated from other contexts. This matters when testing multiple accounts or sessions in one browser process.

• Named context: call context.setCookie(...) and context.cookies(...) on the context that owns the session.
• Default context: browser.setCookie(...) and browser.cookies(...) are convenience methods for the default context.
• Separate sessions: create a separate browser context for each independent storage state; do not assume a cookie set in one context appears in another.

Puppeteer’s cookie guide covers getting, setting, and deleting cookies and notes that equivalent methods are available on BrowserContext.

5. Read, update, and delete cookies

Use the same context for inspection and removal. Cookie deletion depends on identifying the cookie and its scope; inspect the values returned by the API when diagnosing a mismatch.

// Read cookies visible to this context for a URL.
const before = await context.cookies('https://example.com/');
console.log(before);

// Set or replace a cookie by its identifying scope and name.
await context.setCookie({
  name: 'session_hint',
  value: 'updated-value',
  domain: 'example.com',
  path: '/',
  secure: true,
});

// Delete the cookie from this context.
await context.deleteCookie({
  name: 'session_hint',
  domain: 'example.com',
  path: '/',
});

When a cookie does not disappear or a page does not reflect an update, verify that the operation targeted the same context and that the cookie’s domain and path match the site and request being inspected.

6. Session cookies, expiry, and security flags

Omitting expires creates a session cookie according to the field reference. Supply an expiration only when the test or workflow needs a persistent cookie, and use the representation expected by the Puppeteer version you have installed.

• httpOnly: true marks the cookie HttpOnly, which prevents page JavaScript from reading it through the normal document cookie interface.
• secure: true marks the cookie Secure. Use an HTTPS target for a production-like secure-cookie test.
• sameSite controls the cookie’s same-site setting. Choose a value based on the behavior under test and verify it against the installed Puppeteer types and target browser.

Cookie flags do not bypass application authentication or browser policy. A syntactically accepted cookie can still be inapplicable to a request because its scope or security conditions do not match.

7. Partitioned and browser-specific fields

partitionKey, priority, and sourceScheme need special care. Puppeteer documents browser-dependent behavior for partition keys and says priority and source scheme are supported only in Chrome. If a test runs across Chrome and Firefox, avoid asserting identical behavior for these fields unless your chosen browser versions explicitly support it.

Keep tests for optional metadata separate from basic cookie setup. That makes a failure easier to attribute to browser support rather than to cookie name, domain, or context selection.

8. Run the equivalent examples with cURL, Python, and Node.js

These examples call ScreenshotNeo’s screenshot API for a page capture. They are useful when the goal is to capture a rendered page without launching or managing Puppeteer in your application. They do not set a browser cookie: use Puppeteer’s context APIs above when you need to control browser cookie storage.

See the ScreenshotNeo API documentation for request options.

cURL

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

Python

import requests

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

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('shot.webp', bytes));

9. Troubleshooting Puppeteer cookie problems

Symptom	Likely cause	Fix
Cookie is not present in the page request.	Wrong browser context, domain, path, or URL scope.	Set and inspect it on the same context. Check the returned cookie’s scope and query cookies for the target URL.
Cookie exists in one session but not another.	Contexts have isolated storage.	Set it on the context used to create the page; create one context per independent session.
Cookie expires sooner than expected.	expires was omitted, so it is a session cookie, or the supplied value does not match the installed API’s expected format.	Set an explicit expiry using the versioned reference and inspect the resulting cookie.
Page JavaScript cannot read the cookie.	httpOnly is enabled.	Read it through Puppeteer’s cookie API. Only disable HttpOnly if the application behavior being tested calls for that.
Secure cookie does not behave as expected.	The target request does not satisfy the Secure cookie conditions.	Use an HTTPS page for the test and confirm the cookie’s scope.
A browser rejects or ignores optional metadata.	partitionKey, priority, or sourceScheme has browser-specific support.	Check the browser support noted in Puppeteer’s API reference; keep browser-specific expectations conditional.
TypeScript rejects the object or method call.	The object type does not match the API level, or the project’s Puppeteer version differs from the referenced version.	Use CookieData for browser-level methods and CookieParam for page-level methods. Check types installed in the project.

10. Performance, reliability, and cost

Cookie operations are usually a small part of a browser workflow; launching the browser and loading the page are typically the larger operational steps. Reuse a browser process when appropriate, but keep separate contexts for isolated sessions. Always close contexts and browsers in cleanup paths. If navigation is slow or unreliable, choose a wait condition that matches the test: waiting for the full load event can take longer than waiting for DOM content, while waiting too little can capture a page before it is ready.

Puppeteer is a self-managed browser workflow: account for the runtime and infrastructure you use to run it. If your task is only to obtain a rendered screenshot, ScreenshotNeo offers a one-request API. It bills only clean shots; bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, with the outcome indicated in X-Page-Verdict and X-Billed response headers. Plans include 1,000 free shots per month with no card, then paid plans from $5 for 3,000 shots. Every feature is on every plan; yearly billing gives two months free.

11. Or skip the browser setup

For a screenshot of a URL, send one request to ScreenshotNeo. Its capture flow accepts cookie or consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before the shot; each step can be turned off. Bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents 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.

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

See the API docs and sign up for 1,000 free screenshots a month, with no card.

12. FAQ

Does CookieData represent a browser’s stored cookie?

It is the parameter object used to set browser-level cookies. Use cookies() to retrieve stored cookie data.

Can I set several cookies at once?

The browser-level setCookie(...cookies) method accepts one or more CookieData objects.

Does setting a cookie log a user into a site?

Only if the application recognizes that cookie and its scope and security conditions match the relevant requests. Puppeteer does not create a valid application session by itself.

Where should I check exact field types?

Use the API reference for the Puppeteer version installed in your project, especially for expiry representation, same-site values, and browser-specific optional fields.