How to capture a webpage screenshot with an API key

To capture a webpage with an API key, send an HTTP request to a screenshot service’s documented endpoint, authenticate the request using that service’s required header or parameter, and save the successful response as an image. Keep the key on a server. The key authorizes your use of the screenshot API; it does not automatically sign the browser in to the target website.

Endpoint paths, token permissions, request methods, and response formats differ by provider. The examples below show Cloudflare Browser Run and ScreenshotEngine as vendor-specific implementations. Follow the current documentation for the service you use.

1. Choose the API and identify its authentication method

Before writing code, check four things in the provider’s documentation:

API authentication: Is the key sent as a Bearer token, a query parameter, or another supported credential? What permission does it need?
Target-page access: Can the browser send cookies, HTTP Basic credentials, or authorization headers to the page being captured?
Capture controls: Which options control full-page capture, viewport size, element selection, and page-load waits?
Response format: Does a successful request return image bytes, a URL, or a different structure? What does an error response look like?

These are separate questions: a screenshot service key authenticates your API call, while cookies or credentials authenticate the browser with a protected target page.

2. Make a basic Cloudflare Browser Run request

Cloudflare Browser Run’s REST endpoint accepts a POST request with either a url or html field. Its endpoint guide says to use a custom API token with Browser Rendering - Edit permission. Cloudflare also supports a Workers Binding path for Browser Rendering that does not require an API token. See the Cloudflare Browser Rendering documentation for current setup details.

curl -X POST 'https://api.cloudflare.com/client/v4/accounts/<accountId>/browser-run/screenshot' \
  -H 'Authorization: Bearer <apiToken>' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com"}' \
  --output screenshot.png

Replace <accountId> and <apiToken> with your own values. Store the token in server-side secret storage or an environment variable; do not paste a real token into a published command, repository, or browser code.

Set capture options

Cloudflare’s screenshot request supports options such as screenshotOptions.fullPage, viewport, gotoOptions, and selector. For example, a request body can specify a viewport and a page-load wait:

{
  "url": "https://example.com",
  "screenshotOptions": {
    "fullPage": true
  },
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "gotoOptions": {
    "waitUntil": "networkidle0",
    "timeout": 45000
  }
}

Those values illustrate available controls; they are not universal defaults or a guarantee that every site will become idle within that interval. To capture a particular element, the Cloudflare guide shows a selector option. Check its current API reference for the exact request schema and supported values.

3. Keep API credentials separate from target-page credentials

If the destination requires a login, the screenshot API token alone usually will not grant access to it. The browser may need a session cookie, HTTP Basic credentials, or an authorization header sent to the destination. Cloudflare documents these target-page mechanisms, including session cookies, authenticate, and setExtraHTTPHeaders. Configure them according to the provider’s documentation and the target site’s access rules.

Do not assume another provider supports the same controls. ScreenshotEngine documents its endpoint for public URLs and says it does not expose custom cookies, target-site Authorization headers, or login scripts. Protected-page support is provider-specific.

4. Save and validate the response

A successful response may contain image bytes directly, but error responses may instead contain JSON. Check the HTTP status and Content-Type before treating the body as an image. ScreenshotEngine’s quickstart documents HTTP 200 with image bytes for success and JSON for errors; verify the behavior for the API you choose.

For Cloudflare’s command-line example, curl writes the response body to screenshot.png. If your integration needs robust error handling, make the request in application code and only write the body after checking the response status and content type.

5. Protect the API key

Keep the key in server-side secret storage or a server-only environment variable.
Never put it in browser JavaScript, a public environment variable, a public repository, or a link that users can inspect.
Avoid logging Authorization headers or key-bearing query strings. ScreenshotEngine specifically warns that query-string keys can leak through URLs and recommends POST for server integrations where supported.
If a key is exposed, revoke or replace it using the provider’s key-management process.
Use only the permissions needed for the integration, following the selected endpoint’s documentation.

Authentication schemes are vendor-specific. Cloudflare’s API reference lists API tokens as preferred authorization and also documents legacy X-Auth-Email and X-Auth-Key headers. The endpoint-specific Browser Run guide calls for Browser Rendering - Edit; the API reference lists Browser Rendering Write among accepted permissions. Check the current endpoint guide and API reference when creating a token rather than assuming these permission names are interchangeable.

6. Common errors and fixes

Symptom	Likely cause	What to check
Unauthorized or forbidden response	The token is missing, invalid, expired, or lacks the endpoint’s required permission.	Confirm the header format, account ID, token validity, and required permission in the provider’s endpoint documentation.
The saved file is JSON or cannot be opened as an image	The request failed, and the client saved the error body as if it were image bytes.	Check HTTP status and `Content-Type`; inspect the error response before saving.
The page shows a login screen	The API key authenticated the screenshot request, but the browser did not have target-site credentials.	Check whether the provider supports the needed cookies, Basic authentication, or target authorization headers. Some services only capture public URLs.
The capture is incomplete or blank	The page may not have finished rendering, may require a different wait condition, or may block automated browsers.	Review the provider’s load-wait options and response diagnostics. Do not assume a wait value that works for one site works for all sites.
Request times out	The site is slow, the selected wait condition never completes, or the timeout is too short for the page.	Check the provider’s timeout and navigation options, then choose a wait condition appropriate for the target page.
Works in a private script but not in frontend code	A server-side secret was moved into public client code or the browser request is blocked by the service’s access policy.	Call the screenshot API from your server and return only the resulting image or a controlled URL to the client.

7. Performance, reliability, and cost considerations

Capture time depends on the target page, its assets, the selected wait condition, and the provider. Full-page capture and waits for network idleness can take longer than a viewport capture with a suitable readiness condition. Choose the least restrictive wait that still produces the content your application needs, and set timeouts based on the provider’s documented limits.

For reliability, handle non-success status codes, validate response types, and treat a timeout or failed navigation as a failed capture rather than a valid image. If you retry, use a bounded retry policy; repeated requests can create extra work or cost depending on the provider’s billing rules. The research for this guide does not establish comparable pricing, latency, quotas, or service guarantees across providers, so check the current plan and terms before estimating production costs.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. Send one GET request with a URL to receive a PNG, JPEG, WebP, or PDF. The ScreenshotNeo API documentation has request options and details.

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}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

Keep the access key on your server, including when using a GET request. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its 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 shots.

FAQ

Does an API key log the browser in to the website?

No. It authenticates the request to the screenshot service. A protected target site may require separate cookies or credentials, if the provider supports them.

Can I use an API key in frontend JavaScript?

Do not expose a secret key in public client code. Make the authenticated request from a server you control.

Is the Cloudflare request format universal?

No. Endpoints, methods, permission names, options, and response formats vary. Use the selected provider’s current documentation.

No. Support for cookies, Basic credentials, authorization headers, or login flows varies by service; some documented endpoints are for public pages only.