Quickstart

Capture your first screenshot in a few minutes with an official SDK.

In this guide, you'll get an access key, add the official SDK to your project, and send your first capture request.

Get your access key

Sign up for Screenshot Scout or sign in. We automatically create a default API key for you when you sign up. Open the API Keys page and copy the access key.

You won't need the secret key for this guide. It's only used for signed requests.

Install the SDK

Install the package from npm:

npm install @screenshotscout/sdk

The SDK requires Node.js 22 or newer.

Install the package from PyPI:

pip install screenshotscout

The SDK requires Python 3.11 or newer.

Install the package with Composer:

composer require screenshotscout/sdk

The SDK requires PHP 8.3 or newer.

Add the dependency to your Maven project's pom.xml:

<dependency>
  <groupId>com.screenshotscout</groupId>
  <artifactId>screenshotscout</artifactId>
  <version>0.3.0</version>
</dependency>

With Gradle, add it to the dependencies block in build.gradle.kts instead:

implementation("com.screenshotscout:screenshotscout:0.3.0")

The SDK requires Java 17 or newer.

Install the package from NuGet:

dotnet add package ScreenshotScout

The SDK requires .NET 8 or later.

Add the module to your project:

go get github.com/screenshotscout/screenshotscout-go

The SDK requires Go 1.25 or newer.

Add the gem to your bundle:

bundle add screenshotscout

The SDK requires Ruby 3.4 or newer.

There's nothing to install. curl comes with macOS, most Linux distributions, and Windows 10 and later.

Capture a screenshot

Add this code to your app, or run it on its own to try it first. Replace YOUR_ACCESS_KEY with your access key.

import { writeFile } from "node:fs/promises";
import { ScreenshotScoutClient } from "@screenshotscout/sdk";

const client = new ScreenshotScoutClient({ accessKey: "YOUR_ACCESS_KEY" });

const response = await client.capture("https://example.com/");

await writeFile("screenshot.png", response.bytes);

from pathlib import Path

from screenshotscout import ScreenshotScoutClient

client = ScreenshotScoutClient("YOUR_ACCESS_KEY")

response = client.capture("https://example.com/")

Path("screenshot.png").write_bytes(response.bytes)

<?php

use ScreenshotScout\Client;

require __DIR__ . '/vendor/autoload.php';

$client = new Client('YOUR_ACCESS_KEY');

$response = $client->capture('https://example.com/');

file_put_contents('screenshot.png', $response->bytes());

import com.screenshotscout.BinaryCaptureResponse;
import com.screenshotscout.ScreenshotScoutClient;
import java.nio.file.Files;
import java.nio.file.Path;

public class Main {
    public static void main(String[] args) throws Exception {
        var client = ScreenshotScoutClient.builder().accessKey("YOUR_ACCESS_KEY").build();

        var response = (BinaryCaptureResponse) client.capture("https://example.com/");
        Files.write(Path.of("screenshot.png"), response.bytes());
    }
}

using ScreenshotScout;

using var client = new ScreenshotScoutClient("YOUR_ACCESS_KEY");

var response = (BinaryCaptureResponse)await client.CaptureAsync("https://example.com/");

await File.WriteAllBytesAsync("screenshot.png", response.Bytes);

package main

import (
	"context"
	"log"
	"os"

	screenshotscout "github.com/screenshotscout/screenshotscout-go"
)

func main() {
	client, err := screenshotscout.NewClient("YOUR_ACCESS_KEY", nil)
	if err != nil {
		log.Fatal(err)
	}

	response, err := client.Capture(context.Background(), "https://example.com/", nil)
	if err != nil {
		log.Fatal(err)
	}

	if err := os.WriteFile("screenshot.png", response.Binary.Bytes, 0o644); err != nil {
		log.Fatal(err)
	}
}

require "screenshotscout"

client = ScreenshotScout::Client.new(access_key: "YOUR_ACCESS_KEY")

response = client.capture("https://example.com/")

File.binwrite("screenshot.png", response.bytes)

curl "https://api.screenshotscout.com/v1/capture" \
  -H "Authorization: Bearer YOUR_ACCESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/"
  }' \
  -o "screenshot.png"

Run the command in a terminal. On Windows, run it in Git Bash or WSL, because PowerShell can't run it as written. If the request fails, screenshot.png contains the JSON error instead of an image.

The code saves the screenshot as screenshot.png, so you can open it and check the result. You can also get a JSON response with a temporary screenshot URL, or build a capture URL that returns the screenshot when requested. Your SDK's page shows both.

Troubleshooting

When a capture fails, the API returns an error code and a message, and each SDK turns them into an error with the same code and message.

What you see	What to do
`access_key_required` or `access_key_invalid`	Check that you replaced `YOUR_ACCESS_KEY` with your access key and copied all of it.
`signature_required`	The API key has Require signed requests enabled. For this guide, use a key without it, or pass the secret key to the SDK client so it signs requests for you.
`invalid_options`	The `errors` array names each invalid option and explains what's wrong with it.

Errors lists every error code.

Before you go live

Screenshot URLs expire. The screenshot URL in the Screenshot-Scout-Screenshot-URL header or in a JSON response works for 4 hours by default. To keep a screenshot, store the image yourself, or set storage_mode to external so we upload it to your own S3-compatible bucket.
Capture URLs contain your access key. Before you share a capture URL or put it in a web page, sign it and enable Require signed requests for the key. Each SDK can build signed capture URLs for you.

Quickstart

Get your access key

Install the SDK

Capture a screenshot

Troubleshooting

Before you go live

Next steps

API Reference

Screenshot Options

Signed Requests

Errors

SDKs

On this page