Authentication

Every Screenshotly API request is authenticated with a workspace API key. Keys start with scr_, are created in the dashboard, and are stored only as hashes, so the plaintext value is shown once.

Get an API key

Sign in to the Screenshotly dashboard with a verified email address.
Open API keys.
Choose the workspace the key belongs to and, optionally, give it a name such as production or ci.
Click Generate New Key and copy the key immediately. You cannot view it again.

Keys created in the dashboard expire 30 days after creation. See Managing API keys for rotation and revocation.

Send the key

Use either header. Both are accepted on every endpoint.

x-api-key: scr_your_api_key

Authorization: Bearer scr_your_api_key

curl --fail-with-body https://screenshotly.app/api/screenshot \
  -X POST \
  -H "Authorization: Bearer $SCREENSHOTLY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com"}' \
  --output screenshot.png

const response = await fetch('https://screenshotly.app/api/screenshot', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SCREENSHOTLY_API_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify({ url: 'https://example.com' }),
});

import os

import requests

response = requests.post(
    "https://screenshotly.app/api/screenshot",
    headers={"Authorization": f"Bearer {os.environ['SCREENSHOTLY_API_KEY']}"},
    json={"url": "https://example.com"},
    timeout=60,
)

Call the API from a server, worker, or CI job. Never ship a key in browser or mobile app code, where anyone can read it.

Authentication errors

Authentication runs before request validation. Error responses are JSON:

{
  "error": "Authentication failed",
  "message": "Invalid API key"
}

Status	`message`	Cause
`401`	`API key is required…`	Neither header was sent.
`401`	`Invalid API key`	The key is unknown, revoked, or expired.
`403`	`Email verification required`	The workspace owner’s email address is not verified.

A 403 with "error": "Plan upgrade required" is different: the key is valid, but the workspace owner’s plan does not include a requested feature. The response names the feature and includes minimumPlan.

Rate limits

Two limits apply, and both belong to the workspace owner’s account, not to an individual key. Creating more keys does not increase either limit.

Plan	Successful captures	Requests per minute
Free	100 in total	5
Basic	2,500 per month	40
Growth	12,000 per month	80
Scale	50,000 per month	200

Capture allowance. Only successful captures count. Paid allowances reset at the start of each calendar month (UTC). An owner can set a lower hard stop in Account Controls; see Teams, usage, and retention.
Throughput. Requests are counted per one-minute window. Every capture request that passes validation counts toward this limit, whether or not the capture succeeds.

Response headers

Successful POST /api/screenshot responses include:

X-RateLimit-Limit: 2500
X-RateLimit-Remaining: 2417
X-Screenshot-Duration: 1840
X-Screenshot-Size: 482113

X-RateLimit-Limit and X-RateLimit-Remaining describe the capture allowance for the current period (after any hard stop), not per-minute throughput. X-Screenshot-Duration is in milliseconds and X-Screenshot-Size in bytes.

`429 Too Many Requests`

When either limit is reached, POST /api/screenshot and POST /api/jobs return 429 with a Retry-After header in seconds. POST /api/jobs/batch also returns 429 when the batch is larger than your remaining allowance, without a Retry-After header.

{
  "error": "Rate limit exceeded",
  "message": "Request rate limit exceeded",
  "retryAfter": 23
}

Wait at least Retry-After seconds before retrying. If message says the limit resets at a date, the capture allowance is used up: retrying will not help until that date or until the plan changes.

Next steps

Managing API keys: rotation, expiry, and revocation
Security: how keys, payloads, and captures are protected
Synchronous capture: the full request reference

Getting Started

API Reference

Guides

Get an API key

Send the key

Authentication errors

Rate limits

Response headers

`429 Too Many Requests`

Next steps