Supacrawler Docs
API Reference

Screenshots

Capture high-quality screenshots of any webpage with customizable device settings and formats. Perfect for visual testing, content verification, and automated monitoring.

Use cases

Essential for visual regression testing and dynamic OG image generation.

Screenshots are processed asynchronously. The API returns a job ID immediately, and the screenshot URL is generated after processing completes as a short-lived signed URL.

Quick Example

curl -X POST https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "desktop",
    "full_page": true,
    "format": "png"
  }'
from supacrawler import SupacrawlerClient
import os

client = SupacrawlerClient(api_key=os.environ.get('SUPACRAWLER_API_KEY'))
job = client.create_screenshot_job(
    url='https://example.com',
    device='desktop',
    full_page=True,
    format_='png'
)

final = client.wait_for_job(job.job_id)
if final.status == 'completed' and hasattr(final.data, 'screenshot'):
    print('Screenshot URL:', final.data.screenshot)
import { SupacrawlerClient } from '@supacrawler/js'

const client = new SupacrawlerClient({ apiKey: process.env.SUPACRAWLER_API_KEY })
const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: 'desktop',
  full_page: true,
  format: 'png'
})

const status = await client.waitForJob(job.job_id)
if (status.status === 'completed' && 'screenshot' in status.data) {
  console.log('Screenshot URL:', status.data.screenshot)
}
Job Created
{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "processing"
}

Example Screenshot

TODO: Add screenshot image here - The example screenshot from https://supacrawler.com/screenshots/crawler.webp will be available once deployed.

Create Screenshot Job

Endpoint

POST /v1/screenshots

Create an asynchronous screenshot job.

Parameters

Prop

Type

Request

curl -X POST https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "device": "mobile",
    "full_page": true,
    "dark_mode": true
  }'
import requests

response = requests.post(
    "https://api.supacrawler.com/api/v1/screenshots",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "url": "https://example.com",
        "device": "mobile",
        "full_page": True,
        "dark_mode": True
    }
)
print(response.json())
const response = await fetch(
  'https://api.supacrawler.com/api/v1/screenshots',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: 'https://example.com',
      device: 'mobile',
      full_page: true,
      dark_mode: true
    })
  }
);

const result = await response.json();
console.log(result);

Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "type": "screenshot",
  "status": "processing",
  "url": "https://example.com",
  "metadata": {
    "device": "mobile"
  }
}

Important to know

Creating a screenshot returns only a job ID. The actual screenshot URL is generated after processing completes as a short-lived signed URL. Retrieve it by calling GET /v1/screenshots?job_id=....

Get Screenshot

Endpoint

GET /v1/screenshots?job_id={jobId}

Retrieve the screenshot URL for a completed job. Returns a fresh 15-minute signed URL.

Parameters

Prop

Type

Request

curl "https://api.supacrawler.com/api/v1/screenshots?job_id=550e8400-e29b-41d4-a716-446655440001" \
  -H "Authorization: Bearer YOUR_API_KEY"
import requests

job_id = "550e8400-e29b-41d4-a716-446655440001"
response = requests.get(
    f"https://api.supacrawler.com/api/v1/screenshots?job_id={job_id}",
    headers={"Authorization": "Bearer YOUR_API_KEY"}
)
print(response.json())
const jobId = '550e8400-e29b-41d4-a716-446655440001';
const response = await fetch(
  `https://api.supacrawler.com/api/v1/screenshots?job_id=${jobId}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);

const result = await response.json();
console.log(result);

Response

{
  "success": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440001",
  "screenshot": "https://storage.supacrawler.com/screenshots/550e8400.png",
  "status": "completed",
  "metadata": {
    "width": 375,
    "height": 667,
    "format": "png",
    "file_size": 245760,
    "load_time": 1250
  }
}

Response Model

Prop

Type

Device Presets

Prop

Type

Basic Screenshot

from supacrawler import SupacrawlerClient
import os

client = SupacrawlerClient(api_key=os.environ['SUPACRAWLER_API_KEY'])

# Create screenshot job
job = client.create_screenshot_job(
    url='https://example.com',
    device='desktop',
    full_page=True
)

# Wait for completion
final = client.wait_for_job(job.job_id)
print(f"Screenshot URL: {final.data.screenshot}")
import { SupacrawlerClient } from '@supacrawler/js'

const client = new SupacrawlerClient({ 
  apiKey: process.env.SUPACRAWLER_API_KEY 
})

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: 'desktop',
  full_page: true
})

const status = await client.waitForJob(job.job_id)
console.log('Screenshot URL:', status.data.screenshot)
# Create job
curl -X POST https://api.supacrawler.com/api/v1/screenshots \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://example.com",
    "device": "desktop",
    "full_page": true
  }'

# Get result
curl "https://api.supacrawler.com/api/v1/crawl/{job_id}" \
  -H "Authorization: Bearer YOUR_API_KEY"

Mobile Screenshots

job = client.create_screenshot_job(
    url='https://example.com',
    device='mobile',
    full_page=True
)

Dark Mode Screenshots

job = client.create_screenshot_job(
    url='https://example.com',
    device='desktop',
    dark_mode=True
)

Custom Dimensions

job = client.create_screenshot_job(
    url='https://example.com',
    device='custom',
    width=1200,
    height=630,  # Perfect for OG images
    format='png'
)

Hide Elements

job = client.create_screenshot_job(
    url='https://example.com',
    hide_selectors=['.cookie-banner', '#chat-widget'],
    block_ads=True
)

Common Use Cases

Visual Regression Testing

import hashlib

# Take screenshot
job = client.create_screenshot_job(url='https://myapp.com')
final = client.wait_for_job(job.job_id)

# Download and hash
import requests
img_data = requests.get(final.data.screenshot).content
current_hash = hashlib.md5(img_data).hexdigest()

# Compare with baseline
if current_hash != baseline_hash:
    print("⚠️ Visual regression detected!")

Social Media Previews

# Generate OG image
job = client.create_screenshot_job(
    url='https://myblog.com/article',
    device='custom',
    width=1200,
    height=630,
    wait_for_selector='.article-hero'
)

Best Practices

  1. Use appropriate device: Desktop for web apps, mobile for responsive sites
  2. Wait for elements: Use wait_for_selector for dynamic content
  3. Hide distractions: Block ads and cookie banners
  4. Optimize format: PNG for quality, JPEG for smaller files
  5. Cache results: Screenshots are expensive, cache when possible

Was this page helpful?

Parse

AI-powered data extraction using natural language prompts with customizable schemas. Transform natural language requests into structured web data automatically.

Watch

Monitor websites for changes and get notified when content updates are detected. Create watch jobs that automatically check for updates on your schedule.

On this page

Quick Example
Example Screenshot
Create Screenshot Job
Endpoint
Parameters
Request
Response
Get Screenshot
Endpoint
Parameters
Request
Response
Response Model
Device Presets
Basic Screenshot
Mobile Screenshots
Dark Mode Screenshots
Custom Dimensions
Hide Elements
Common Use Cases
Visual Regression Testing
Social Media Previews
Best Practices