Skip to main content
The official screenshotly-js package provides a convenient interface for the Screenshotly API in Node.js.

​
Installation

npm install screenshotly-js

​
Setup

const { Screenshotly } = require('screenshotly-js');

// Simple setup
const client = new Screenshotly('your-api-key-here');

// Advanced setup with options
const client = new Screenshotly({
  apiKey: 'your-api-key-here',
  baseUrl: 'https://api.screenshotly.dev', // optional
  timeout: 60000 // optional, in milliseconds
});
Store your API key in an environment variable, not in your source code:
const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);

​
Capture a screenshot

const screenshot = await client.capture({
  url: 'https://example.com',
  viewport_width: 1280,
  viewport_height: 800,
  format: 'png'
});

if (screenshot.success) {
  console.log('Screenshot URL:', screenshot.data.imageUrl);
  console.log('Remaining credits:', screenshot.remainingCredits);
} else {
  console.error('Error:', screenshot.error);
}

​
Capture options

ParameterTypeDefaultDescription
urlstring—URL to capture (required)
namestring—Optional name for the screenshot
viewport_widthnumber1280Viewport width in pixels (100–5000)
viewport_heightnumber1024Viewport height in pixels (100–5000)
full_pagebooleanfalseCapture the full scrollable page
formatstring'png'Output format: 'png', 'jpeg', 'webp', 'pdf'
image_qualitynumber80Image quality for JPEG/WebP/PDF (0–100)
device_scale_factornumber1Device pixel ratio (1–3, use 2 for retina)
viewport_mobilebooleanfalseEmulate mobile device
viewport_has_touchbooleanfalseEnable touch events
viewport_landscapebooleanfalseLandscape orientation
wait_for_selectorstring—CSS selector to wait for
selectorstring—CSS selector of element to capture
delaynumber0Delay in ms before capture (0–10000)
timeoutnumber60000Request timeout in ms (1000–90000)
block_adsbooleanfalseBlock advertisements
block_cookie_bannersbooleanfalseBlock cookie consent banners
block_chatsbooleanfalseBlock chat widgets
dark_modeboolean—Emulate dark color scheme
response_typestring'by_format'Response format: 'by_format', 'json', 'empty'

​
Batch capture

Capture multiple URLs with shared settings (max 50 URLs per request): 
const result = await client.captureBatch({
  urls: [
    'https://example.com',
    'https://google.com',
    'https://github.com'
  ],
  options: {
    format: 'png',
    viewport_width: 1280,
    viewport_height: 800,
    full_page: true
  }
});

if (result.success) {
  console.log(`Succeeded: ${result.succeededCount}, Failed: ${result.failedCount}`);
  console.log('Remaining credits:', result.remainingCredits);
}

​
List screenshots

Retrieve your captured screenshots with pagination: 
const screenshots = await client.getScreenshots(1, 10); // page 1, 10 per page
console.log('Screenshots:', screenshots.data);

​
Get a screenshot by ID

const screenshot = await client.getScreenshot('67b8a1c2d3e4f5a6b7c8d9e0');
console.log('Status:', screenshot.data.status);
console.log('URL:', screenshot.data.imageUrl);

​
Delete a screenshot

const result = await client.deleteScreenshot('67b8a1c2d3e4f5a6b7c8d9e0');
console.log('Deleted:', result.success);

​
Error handling

try {
  const screenshot = await client.capture({
    url: 'https://example.com'
  });

  if (!screenshot.success) {
    console.error('Capture failed:', screenshot.error);
  }
} catch (error) {
  // Network errors, timeouts, etc.
  console.error('Request failed:', error.message);
}

​
Using with ES modules

import { Screenshotly } from 'screenshotly-js';

const client = new Screenshotly(process.env.SCREENSHOTLY_API_KEY);