Screenshots Endpoint

Basic Usage

import { SupacrawlerClient, ScreenshotCreateRequest } from '@supacrawler/js'

const client = new SupacrawlerClient({ apiKey: 'YOUR_API_KEY' })

// Create screenshot job
const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  full_page: false
})

// Wait for completion
const result = await client.waitForScreenshot(job.job_id!, {
  timeoutMs: 30000
})

console.log(`screenshot URL: ${result.screenshot}`)
console.log(`size: ${result.metadata?.width}x${result.metadata?.height}`)

Device Presets

Desktop

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  full_page: false
})

Mobile Portrait

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.MOBILE,
  format: ScreenshotCreateRequest.format.JPEG,
  quality: 90,
  full_page: true,
  is_landscape: false  // Portrait mode
})

Tablet Landscape

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.TABLET,
  format: ScreenshotCreateRequest.format.PNG,
  is_landscape: true
})

Custom Size

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.CUSTOM,
  width: 1200,
  height: 800,
  device_scale: 1.5,
  format: ScreenshotCreateRequest.format.PNG,
  is_mobile: false,
  has_touch: false
})

Image Formats

PNG

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG
})

JPEG with Quality

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.JPEG,
  quality: 95  // 1-100
})

Dark Mode

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  dark_mode: true
})

Content Blocking

const job = await client.createScreenshotJob({
  url: 'https://news-site.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  
  // Block unwanted content
  block_ads: true,
  block_cookies: true,
  block_trackers: true,
  block_resources: ['image', 'font'],  // Block images and fonts
  
  // Hide elements
  hide_selectors: ['footer', '.social-links', '#newsletter-popup'],
  
  // Wait for content
  wait_until: ScreenshotCreateRequest.wait_until.DOMCONTENTLOADED,
  delay: 2
})

Waiting Strategies

Network Idle

const job = await client.createScreenshotJob({
  url: 'https://dynamic-site.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  wait_until: ScreenshotCreateRequest.wait_until.NETWORKIDLE,
  delay: 1
})

Wait for Selector

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  wait_for_selector: 'body',
  wait_until: ScreenshotCreateRequest.wait_until.NETWORKIDLE,
  delay: 3,
  timeout: 30
})

Accessibility Features

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.TABLET,
  format: ScreenshotCreateRequest.format.PNG,
  
  // Accessibility settings
  dark_mode: true,
  reduced_motion: true,
  high_contrast: true,
  
  user_agent: 'Mozilla/5.0 (iPad; CPU OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15',
  is_landscape: true
})

Custom Headers and Cookies

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.JPEG,
  quality: 95,
  
  // Custom headers
  headers: {
    'Accept-Language': 'en-US,en;q=0.9',
    'X-Custom-Header': 'typescript-screenshot-example'
  },
  
  // Custom cookies
  cookies: [
    {
      name: 'theme',
      value: 'dark',
      domain: 'example.com'
    },
    {
      name: 'session_id',
      value: 'abc123',
      path: '/',
      httpOnly: true
    }
  ]
})

Element Interaction

const job = await client.createScreenshotJob({
  url: 'https://example.com',
  device: ScreenshotCreateRequest.device.DESKTOP,
  format: ScreenshotCreateRequest.format.PNG,
  
  // Click element before screenshot
  click_selector: 'button.accept-cookies',
  
  wait_for_selector: 'main',
  wait_until: ScreenshotCreateRequest.wait_until.NETWORKIDLE,
  delay: 3,
  full_page: true
})

Complete Example

import { SupacrawlerClient, ScreenshotCreateRequest } from '@supacrawler/js'

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

async function runExamples() {
  console.log('🚀 screenshot examples')

  // Example 1: Basic desktop
  const job1 = await client.createScreenshotJob({
    url: 'https://antoineross.com',
    device: ScreenshotCreateRequest.device.DESKTOP,
    format: ScreenshotCreateRequest.format.PNG,
    full_page: false
  })

  const result1 = await client.waitForScreenshot(job1.job_id!, {
    timeoutMs: 30000
  })
  console.log(`\n✅ desktop screenshot: ${result1.screenshot}`)
  console.log(`size: ${result1.metadata?.width}x${result1.metadata?.height}`)

  // Example 2: Mobile with dark mode
  const job2 = await client.createScreenshotJob({
    url: 'https://antoineross.com',
    device: ScreenshotCreateRequest.device.MOBILE,
    format: ScreenshotCreateRequest.format.JPEG,
    quality: 90,
    dark_mode: true,
    full_page: true
  })

  const result2 = await client.waitForScreenshot(job2.job_id!, {
    timeoutMs: 30000
  })
  console.log(`\n✅ mobile dark mode: ${result2.screenshot}`)

  // Example 3: Content blocking
  const job3 = await client.createScreenshotJob({
    url: 'https://example.com',
    device: ScreenshotCreateRequest.device.DESKTOP,
    format: ScreenshotCreateRequest.format.PNG,
    block_ads: true,
    block_cookies: true,
    block_trackers: true,
    wait_until: ScreenshotCreateRequest.wait_until.NETWORKIDLE,
    delay: 2
  })

  const result3 = await client.waitForScreenshot(job3.job_id!, {
    timeoutMs: 45000
  })
  console.log(`\n✅ content blocked: ${result3.screenshot}`)
}

runExamples().catch(console.error)

Response Structure

interface ScreenshotResponse {
  screenshot: string  // Signed URL (expires in 15 min)
  metadata?: {
    width: number
    height: number
    format: string      // 'png' | 'jpeg'
    file_size: number   // Bytes
    load_time: number   // Milliseconds
    quality?: number    // JPEG quality
  }
}

Error Handling

try {
  const job = await client.createScreenshotJob({
    url: 'https://example.com',
    device: ScreenshotCreateRequest.device.DESKTOP,
    format: ScreenshotCreateRequest.format.PNG
  })

  const result = await client.waitForScreenshot(job.job_id!, {
    timeoutMs: 30000
  })

  if (result.screenshot) {
    console.log(`✅ screenshot captured: ${result.screenshot}`)
  }
} catch (error) {
  console.error('screenshot failed:', error)
}

Next Steps

Scrape Endpoint - Extract page content
Watch Endpoint - Monitor visual changes
Crawl Endpoint - Capture multiple pages

Was this page helpful?

Screenshots Endpoint

On this page