Documentation

The comprehensive guide to integrating the len.sh screenshot API into your development workflow.

Quick Start Guide

1

Get your API Key

Create an account at the signup page. Your unique API key is shown once — store it securely.

2

Make your first request

Call the /v1/screenshot endpoint with the url parameter.

3

Get your screenshot

The API returns the raw image binary. Use the endpoint URL directly as an img src or save to a file.

Authentication

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

HTTP Header (Recommended)

Authorization: Bearer <key>

Query Parameter

?access_key=YOUR_API_KEY

Parameter Reference

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

Parameter Type Default Description
url string — Target URL to capture. Required*
html string — Raw HTML to render (use POST). Required*
format enum png Output format: png, jpeg, webp
width int 1280 Viewport width in pixels (1–3840).
height int 720 Viewport height in pixels (1–2160).
quality int 80 JPEG/WebP quality (1–100, ignored for PNG).
full_page bool false Capture the entire scrollable page.
selector string — CSS selector to capture a specific element.
delay int 0 Wait N ms before capture (0–10000).
wait_until enum load load, domcontentloaded, networkidle0, networkidle2
timeout int 15000 Max wait time in ms (1–30000).
transparent bool false Transparent background (PNG/WebP only).
user_agent string — Custom user agent string.
device_scale number 1 Device scale factor (1–3) for retina.
block_ads bool false Hide common ad elements.
block_cookie_banners bool false Hide cookie consent banners.
cache_ttl int 86400 Cache duration in seconds (0 = bypass, max 2592000).
response_type enum image image (raw bytes) or json (metadata).

*One of url or html is required.

Error Codes

HTTP Code Description
400 MISSING_URL Neither url nor html provided
400 INVALID_URL URL is malformed or uses a blocked protocol
400 INVALID_PARAMETER Parameter value out of range
401 UNAUTHORIZED Missing or invalid API key
429 RATE_LIMITED Too many requests
502 RENDER_FAILED Browser Rendering returned an error
504 RENDER_TIMEOUT Screenshot exceeded timeout

Rate Limits

Rate limits are enforced per API key on an hourly basis. Every response includes headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1709254800

When the limit is exceeded, you'll receive a 429 RATE_LIMITED response. Wait until the reset timestamp and retry.

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.