Skip to main content
Some pages require authentication or specific session data to render correctly. Screenshotly lets you pass cookies, localStorage values, and custom HTTP headers with your capture requests.
Cookies, localStorage, and custom headers are advanced features available on the Pro plan and above.

​
Cookies

Pass an array of cookie objects to set before the page loads. Each cookie follows the standard format: 
const screenshot = await client.capture({
  url: 'https://app.example.com/dashboard',
  cookies: [
    {
      name: 'session_id',
      value: 'your_session_token',
      domain: '.example.com'
    },
    {
      name: 'user_pref',
      value: 'dark_mode',
      domain: '.example.com'
    }
  ]
});
PropertyTypeRequiredDescription
namestringYesCookie name
valuestringYesCookie value
domainstringYesDomain the cookie belongs to
pathstringNoCookie path (defaults to /)
httpOnlybooleanNoHTTP-only flag
securebooleanNoSecure flag

​
localStorage

Set key-value pairs in the page’s localStorage before capture: 
const screenshot = await client.capture({
  url: 'https://app.example.com/settings',
  localStorage: {
    'authToken': 'bearer-token-here',
    'userPreferences': '{"theme":"dark","language":"en"}'
  }
});
localStorage values must be strings. Use JSON.stringify() for objects.

​
Custom HTTP headers

Pass additional HTTP headers with the page request: 
curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api-docs.example.com",
    "headers": {
      "Authorization": "Bearer your-token",
      "X-Custom-Header": "custom-value"
    }
  }'
This is useful for capturing pages behind HTTP-based authentication or pages that render differently based on request headers.
Cookies and custom headers can contain sensitive data. Only send credentials to domains you control. Never log or expose these values.

​
Common scenarios

​
Capturing a logged-in page

const screenshot = await client.capture({
  url: 'https://app.example.com/profile',
  cookies: [
    { name: 'session', value: 'active-session-token', domain: '.example.com' }
  ],
  delay: 2000 // wait for authenticated content to load
});

​
Capturing a page with user preferences

const screenshot = await client.capture({
  url: 'https://example.com',
  localStorage: {
    'theme': 'dark',
    'consentGiven': 'true' // dismiss cookie banner
  }
});

​
Alternative: Use built-in blockers

For common annoyances like cookie banners and chat widgets, you can use the built-in blocking options instead of cookies: 
curl -X POST https://api.screenshotly.dev/v1/capture \
  -H "X-API-Key: $SCREENSHOTLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "options": {
      "block_cookie_banners": true,
      "block_chats": true,
      "block_ads": true
    }
  }' \
  --output clean-screenshot.png