ScreenshotAPI Custom Headers and Cookies for Website Screenshots

To capture a page with ScreenshotAPI using custom request context, pass the headers parameter for HTTP headers, cookies for direct cookie values, or template_id for a saved cookie template. Headers can carry values such as authorization or language preferences; cookies can carry a site session. Use a query-parameter encoder in your client when building the request.

This guide covers ScreenshotAPI’s documented parameter formats. Its documentation does not specify every escaping rule, size limit, or whether an injected header is applied to every subsequent browser request, so validate the format against the current service documentation for values with reserved characters.

1. Choose headers, cookies, or a template

Parameter	Use it when	Documented shape
`headers`	The site expects request metadata such as authorization or a language preference.	`Authorization: Bearer TOKEN; Accept-Language: en-US;`
`cookies`	The session or required page state is represented by one or more cookies.	`session_id=abc123; otherCookie=otherValue;`
`template_id`	You want to reuse a predefined cookie set.	A template identifier, such as `12345`.

These controls reflect different ways a site may represent authentication or request context. A target site’s implementation determines which one it needs; the availability of a parameter does not guarantee that every login flow will work. ScreenshotAPI’s documentation describes cookie data in a template as being applied before navigation.

2. Send custom headers

ScreenshotAPI documents the headers parameter for custom HTTP headers sent before rendering. Multiple header pairs use semicolons as separators. For example:

Authorization: Bearer TOKEN; Accept-Language: en-US;

Replace the example token with the credential the target site expects. Avoid putting a real secret into shell history, source control, logs, or a publicly visible URL. Query strings may be recorded by tools between your application and the API.

cURL

curl -G 'SCREENSHOTAPI_RENDER_ENDPOINT' \
  --data-urlencode 'url=https://example.com/account' \
  --data-urlencode 'headers=Authorization: Bearer TOKEN; Accept-Language: en-US;' \
  -o screenshot.png

Replace SCREENSHOTAPI_RENDER_ENDPOINT with the render endpoint from your ScreenshotAPI account documentation, and replace the URL and token. The research documentation establishes the parameter format but does not provide the endpoint URL, so it is intentionally not guessed here.

Python

import requests

endpoint = "SCREENSHOTAPI_RENDER_ENDPOINT"  # Use the endpoint from your account docs.
params = {
    "url": "https://example.com/account",
    "headers": "Authorization: Bearer TOKEN; Accept-Language: en-US;",
}
response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()
with open("screenshot.png", "wb") as image:
    image.write(response.content)

Node.js

const endpoint = "SCREENSHOTAPI_RENDER_ENDPOINT"; // Use the endpoint from your account docs.
const params = new URLSearchParams({
  url: "https://example.com/account",
  headers: "Authorization: Bearer TOKEN; Accept-Language: en-US;",
});
const response = await fetch(`${endpoint}?${params}`);
if (!response.ok) throw new Error(`Screenshot request failed: ${response.status}`);
await import("node:fs/promises").then(({ writeFile }) =>
  writeFile("screenshot.png", Buffer.from(await response.arrayBuffer()))
);

For direct cookies, ScreenshotAPI documents one or more name=value pairs separated by semicolons:

session_id=abc123; otherCookie=otherValue;

Use a direct cookie string for a one-off request or when assembling the cookie state in your application. For a reusable set, the service supports saving a named Cookie Template and referencing it with template_id. Its login guide describes creating a template from session cookies exported from a browser. Treat exported session cookies like passwords: restrict access, rotate or revoke them when appropriate, and do not commit them to a repository.

cURL with direct cookies

curl -G 'SCREENSHOTAPI_RENDER_ENDPOINT' \
  --data-urlencode 'url=https://example.com/account' \
  --data-urlencode 'cookies=session_id=abc123; otherCookie=otherValue;' \
  -o screenshot.png

Python with a saved template

import requests

endpoint = "SCREENSHOTAPI_RENDER_ENDPOINT"  # Use the endpoint from your account docs.
response = requests.get(
    endpoint,
    params={"url": "https://example.com/account", "template_id": "12345"},
    timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image:
    image.write(response.content)

Node.js with direct cookies

const endpoint = "SCREENSHOTAPI_RENDER_ENDPOINT"; // Use the endpoint from your account docs.
const params = new URLSearchParams({
  url: "https://example.com/account",
  cookies: "session_id=abc123; otherCookie=otherValue;",
});
const response = await fetch(`${endpoint}?${params}`);
if (!response.ok) throw new Error(`Screenshot request failed: ${response.status}`);
const { writeFile } = await import("node:fs/promises");
await writeFile("screenshot.png", Buffer.from(await response.arrayBuffer()));

4. Build and protect the request

Identify what the target expects: an authorization or language header, a session cookie, or a reusable cookie set.
Pass the corresponding documented parameter. Keep the header or cookie value in a secret store or environment configuration rather than hard-coding a real credential.
Encode query parameters with your HTTP library or a tool such as curl --data-urlencode. Do not concatenate raw values into a URL: characters such as spaces and ampersands can change how a query is parsed.
Check the returned HTTP status and confirm the response is an image before treating it as a successful capture. If the output is an error response, preserve its status and diagnostic details for troubleshooting without logging secrets.
Verify the captured page visually. A screenshot can be technically successful while showing a login page, an expired-session message, or a page state different from the one you intended.

ScreenshotAPI’s examples establish semicolon-separated values, but the reviewed documentation does not explain escaping a literal semicolon inside a value, maximum header or cookie sizes, or how broadly custom headers apply to browser subrequests. For those edge cases, consult the current vendor reference and test with non-sensitive credentials.

5. Troubleshoot common failures

Symptom	Likely cause	What to check
The capture shows a login page.	The site expects a different authentication mechanism, the cookie is expired, or the credential is not accepted in the rendered browser context.	Confirm the target’s expected header or cookie names and values, then refresh the session or use the correct saved template.
Only one of several headers appears to work.	The header string may not follow the documented semicolon-separated format, or a value may contain a delimiter that is parsed unexpectedly.	Check spacing and separators. If a value contains a semicolon, verify supported escaping with current ScreenshotAPI documentation.
The request fails after adding a value with punctuation.	The query string may have been assembled without encoding, so reserved characters were interpreted as URL syntax.	Use the client’s parameter encoder or `curl --data-urlencode`. Do not assume that URL encoding resolves the service’s internal parsing of every header or cookie value.
A cookie template does not produce the expected state.	The template ID may be wrong, its cookies may be stale, or the site may require additional state beyond those cookies.	Check the template in the account dashboard and confirm that the login flow still works with that cookie set.
The image file contains an error page or is not a valid image.	The API may have returned an error response or the target may have rendered an unexpected page.	Check the HTTP status and response content type before saving or displaying the result as an image.

6. Performance, reliability, and cost considerations

Headers and cookies configure request context; they do not by themselves make a page load faster or ensure that a site will accept a session. Keep requests focused on the required target URL and avoid sending unnecessary credentials. Reuse a cookie template when its state needs to be maintained centrally, while accounting for session expiry and rotation.

For production workflows, handle timeouts and non-success responses, and make retries bounded. Retrying an invalid token or expired cookie will not repair the underlying authentication problem. A successful HTTP request also does not prove the screenshot shows the intended authenticated page, so validate representative output as part of your application’s own workflow.

The research materials do not establish ScreenshotAPI pricing, quotas, timing benchmarks, or request-size limits. Check its current account and API documentation for those details before estimating cost or throughput.

7. Or skip the browser setup

If you want to capture a URL without managing a browser-rendering integration, ScreenshotNeo is a website screenshot API and MCP server. Its API accepts a URL in one GET request; see the ScreenshotNeo API documentation.

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}`);

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

8. FAQ

Can I use a header for a language preference?

Yes. ScreenshotAPI’s documented header example includes Accept-Language: en-US;.

Can I capture an authenticated dashboard?

ScreenshotAPI presents headers, cookies, and cookie templates for use cases such as login-protected pages. Whether the capture is authenticated depends on the target site’s authentication design and the validity of the supplied state.

Should I send cookies and headers together?

Do so only when the target requires both. The documentation describes each as a separate request option; it does not prescribe a universal combination.

The reviewed documentation does not establish a maximum. Check the current vendor reference for limits before sending large values.