Documentation

Quick Start Guide

Authentication

All API requests (except /v1/health) require an API key. Two methods:

Signed URLs

Signed URLs let you embed screenshots in client-side contexts — img tags, emails, social cards — without exposing your API key. Instead of authenticating with an API key, requests are verified using an HMAC-SHA256 signature computed with a separate signing secret.

How It Works

Example Signed URL

https://api.len.sh/v1/screenshot?key_id=abc123&url=https://example.com&signature=a1b2c3d4...

Security Notes

• check_circle The signing secret is separate from your API key
• check_circle The signing secret can be rotated independently
• check_circle Signed URLs do not expire (designed for static img tags)
• check_circle Rate limiting and monthly quotas still apply

All official SDKs include a signUrl helper that implements this algorithm for you.

Parameter Reference

All parameters work on both GET (query string) and POST (JSON body).

*One of url or html is required.

Device Emulation Presets

Use the device parameter to emulate a specific device. This sets width, height, device scale, and user agent automatically. Explicit parameters override preset values.

OG Image Generation

Generate branded Open Graph images (1200×630) from structured parameters. Uses the same authentication as the screenshot endpoint.

Parameters

Response

Returns raw image bytes with the following headers:

Rate limit and quota headers are also included, identical to the screenshot endpoint.

PDF Generation

Generate PDFs from any URL or HTML content. Uses the same authentication, caching, and rate limiting as the screenshot endpoint.

Parameters

*One of url or html is required.

Response

Returns raw PDF bytes with the following headers:

Use response_type=json to receive metadata (file URL, size, cache status) instead of the raw PDF.

Error Codes

Rate Limits

Rate limits are enforced per API key on a rolling hourly window. The default limit is 100 requests per hour.

Response Headers

Every API response includes rate limit headers so you can track your usage:

When the hourly limit is exceeded, you'll receive a 429 RATE_LIMITED response. Wait until the X-RateLimit-Reset timestamp and retry.

Monthly Quotas

Each plan includes a monthly screenshot quota. When the quota is exceeded, requests return a 429 QUOTA_EXCEEDED error until the next billing month.

Quota Exceeded Response

When your monthly quota is exceeded, the API returns:

Use the X-Quota-Remaining header to track usage and the X-Quota-Reset header to know when the quota resets. If you need more volume, upgrade your plan.

Handling Rate Limits

Best practices for building reliable integrations that respect rate limits.

1. Check Headers Proactively

Monitor the remaining count on every response instead of waiting for a 429 error.

const res = await fetch(url, { headers });
const remaining = res.headers.get("X-Quota-Remaining");

if (remaining !== null && parseInt(remaining) < 10) {
  console.warn(`Low quota: ${remaining} screenshots remaining`);
}

2. Retry with Exponential Backoff

When you receive a 429, wait and retry with increasing delays.

async function captureWithRetry(url, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const res = await fetch(
      "https://api.len.sh/v1/screenshot?url=" + encodeURIComponent(url),
      { headers: { Authorization: "Bearer YOUR_API_KEY" } }
    );

    if (res.status !== 429) return res;

    const reset = res.headers.get("X-RateLimit-Reset");
    const waitMs = reset
      ? Math.max(0, parseInt(reset) * 1000 - Date.now())
      : Math.pow(2, attempt) * 1000;

    await new Promise((r) => setTimeout(r, waitMs));
  }
  throw new Error("Rate limit retries exhausted");
}

3. Use Caching

Avoid redundant captures by using the built-in cache. Cached responses (cache HIT) still count against hourly rate limits, but they don't re-render the page.

// Cache for 24 hours (default)
/v1/screenshot?url=https://example.com&cache_ttl=86400

// Cache for 7 days
/v1/screenshot?url=https://example.com&cache_ttl=604800

4. Distinguish Error Types

Handle hourly rate limits and monthly quotas differently:

• schedule RATE_LIMITED — Wait until X-RateLimit-Reset (usually minutes). Retry the request.
• block QUOTA_EXCEEDED — Monthly limit reached. Either upgrade your plan or wait until the next billing month (X-Quota-Reset).

Caching

Screenshots are cached in Cloudflare R2. The cache key is a SHA-256 hash of all rendering-affecting parameters.

• check_circle Default TTL: 24 hours (86400 seconds)
• check_circle Bypass cache: Set cache_ttl=0
• check_circle Max TTL: 30 days (2592000 seconds)
• check_circle Cache HIT: ~50-100ms response time

Check the X-Len-Cache response header to see if a response was served from cache.