WebScrapingAPI Docs

Multiple Screenshots

Capture named screenshots between browser actions and return them in one request.

Add screenshot actions to an ordered js_instructions array to capture several states of the same page. Each action captures the current page immediately, before the next instruction runs. This supports workflows such as opening Assessments, Sales History, Taxes, and Payments and returning a distinct image of each tab.

Use a GET target request (method=GET, or omit method). Screenshot actions do not require the top-level screenshot=1 parameter. They cannot be combined with download_file, download_file_native, or redirect_chain.

Screenshot action

{
  "action": "screenshot",
  "name": "assessments",
  "options": {
    "full_page": true
  }
}
FieldRequiredDescription
actionYesscreenshot.
nameYesUnique within the request. Use 1–64 ASCII letters, digits, underscores, or hyphens: [A-Za-z0-9_-].
optionsNoScreenshot configuration object. Omit it to capture the current viewport.
options.full_pageNoJSON boolean. Set true to capture the full page.
options.width, options.heightNoTemporarily resize the viewport for this capture. Each must be an integer from 1 to 10000 pixels; an omitted dimension keeps its current size. The original viewport is restored before the next instruction.
options.screenshot_selectorNoNonempty CSS selector for the element to capture. Cannot be combined with full_page: true.
timeoutNoMaximum capture time, 10–60000 ms, also capped by the remaining request budget. It does not add a delay after capture.

Only the listed option keys are accepted. return_html is not an action option. Action options are independent of the top-level screenshot_options, which continues to configure only the final screenshot requested with screenshot=1.

Capture four tabs in order

The example below assumes the target account page has already been reached. Add your account search and navigation instructions before these steps if needed. The URL and selectors are illustrative placeholders: replace them with your target's actual tab buttons and loaded, active panel selectors.

Save the following array as instructions.json beside your client script:

[
  { "action": "click", "selector": "[data-tab='assessments']", "strict": "true" },
  { "action": "wait_for_css", "selector": "[data-panel='assessments'][data-active='true'][data-loaded='true']", "timeout": 10000, "strict": "true" },
  { "action": "screenshot", "name": "assessments", "options": { "full_page": true } },
  { "action": "click", "selector": "[data-tab='sales-history']", "strict": "true" },
  { "action": "wait_for_css", "selector": "[data-panel='sales-history'][data-active='true'][data-loaded='true']", "timeout": 10000, "strict": "true" },
  { "action": "screenshot", "name": "sales_history", "options": { "full_page": true } },
  { "action": "click", "selector": "[data-tab='taxes']", "strict": "true" },
  { "action": "wait_for_css", "selector": "[data-panel='taxes'][data-active='true'][data-loaded='true']", "timeout": 10000, "strict": "true" },
  { "action": "screenshot", "name": "taxes", "options": { "full_page": true } },
  { "action": "click", "selector": "[data-tab='payments']", "strict": "true" },
  { "action": "wait_for_css", "selector": "[data-panel='payments'][data-active='true'][data-loaded='true']", "timeout": 10000, "strict": "true" },
  { "action": "screenshot", "name": "payments", "options": { "full_page": true } }
]

wait_for_css waits for a matching element to exist; it does not by itself verify visibility or populated data. Use a selector that identifies the active and loaded panel. A selector matching a hidden, pre-rendered panel can return too early. Set strict: "true" on the clicks and readiness waits to avoid capturing the previous tab after a failed interaction.

The 10000 values are maximum selector waits, not mandatory ten-second delays and not measured recommendations for a particular website. A timeout on an ordinary click instead adds a fixed delay after the click. Prefer readiness selectors over fixed delays.

Send the request

Set WSA_API_KEY in your server environment and set TARGET_URL to the actual account page URL, replacing the illustrative value https://property.example/account/60334. These examples read instructions.json and let the client encode its JSON into the query string.

: "${WSA_API_KEY:?Set WSA_API_KEY}"
: "${TARGET_URL:?Set TARGET_URL}"
curl --get --fail-with-body --max-time 130 \
  "https://api.webscrapingapi.com/v1" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "url=$TARGET_URL" \
  --data-urlencode "timeout=120000" \
  --data-urlencode "[email protected]"
import { readFile } from "node:fs/promises";

const apiKey = process.env.WSA_API_KEY;
const target = process.env.TARGET_URL;
if (!apiKey || !target) throw new Error("Set WSA_API_KEY and TARGET_URL");
const instructions = JSON.parse(await readFile("instructions.json", "utf8"));
const query = new URLSearchParams({
  api_key: apiKey,
  url: target,
  timeout: "120000",
  js_instructions: JSON.stringify(instructions),
});
const response = await fetch(`https://api.webscrapingapi.com/v1?${query}`, {
  signal: AbortSignal.timeout(130000),
});
if (!response.ok) throw new Error(`API status ${response.status}`);
console.log(await response.json());
import json
import os
import requests

with open("instructions.json", encoding="utf-8") as source:
    instructions = json.load(source)
response = requests.get(
    "https://api.webscrapingapi.com/v1",
    params={
        "api_key": os.environ["WSA_API_KEY"],
        "url": os.environ["TARGET_URL"],
        "timeout": 120000,
        "js_instructions": json.dumps(instructions),
    },
    timeout=130,
)
response.raise_for_status()
print(response.json())
<?php
$apiKey = getenv('WSA_API_KEY');
$target = getenv('TARGET_URL');
if (!$apiKey || !$target) throw new RuntimeException('Set WSA_API_KEY and TARGET_URL');
$instructions = json_decode(file_get_contents('instructions.json'), true, 512, JSON_THROW_ON_ERROR);
$query = http_build_query([
    'api_key' => $apiKey,
    'url' => $target,
    'timeout' => 120000,
    'js_instructions' => json_encode($instructions, JSON_THROW_ON_ERROR),
]);
$curl = curl_init('https://api.webscrapingapi.com/v1?' . $query);
curl_setopt_array($curl, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 130]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if ($body === false) throw new RuntimeException(curl_error($curl));
curl_close($curl);
if ($status >= 400) throw new RuntimeException('API status ' . $status);
echo $body;
package main

import (
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
    "time"
)

func main() {
    apiKey, target := os.Getenv("WSA_API_KEY"), os.Getenv("TARGET_URL")
    if apiKey == "" || target == "" { panic("Set WSA_API_KEY and TARGET_URL") }
    instructions, err := os.ReadFile("instructions.json")
    if err != nil { panic(err) }
    query := url.Values{
        "api_key": {apiKey}, "url": {target}, "timeout": {"120000"},
        "js_instructions": {string(instructions)},
    }
    client := &http.Client{Timeout: 130 * time.Second}
    response, err := client.Get("https://api.webscrapingapi.com/v1?" + query.Encode())
    if err != nil { panic(err) }
    defer response.Body.Close()
    if response.StatusCode >= 400 { panic(fmt.Sprintf("API status %d", response.StatusCode)) }
    body, err := io.ReadAll(response.Body)
    if err != nil { panic(err) }
    fmt.Println(string(body))
}
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.nio.file.*;
import java.time.Duration;
import java.util.*;
import java.util.stream.Collectors;

public class Main {
    public static void main(String[] args) throws Exception {
        String apiKey = Objects.requireNonNull(System.getenv("WSA_API_KEY"), "Set WSA_API_KEY");
        String target = Objects.requireNonNull(System.getenv("TARGET_URL"), "Set TARGET_URL");
        Map<String, String> params = Map.of(
            "api_key", apiKey, "url", target, "timeout", "120000",
            "js_instructions", Files.readString(Path.of("instructions.json")));
        String query = params.entrySet().stream().map(entry ->
            URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8) + "=" +
            URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8)
        ).collect(Collectors.joining("&"));
        HttpRequest request = HttpRequest.newBuilder(
            URI.create("https://api.webscrapingapi.com/v1?" + query))
            .timeout(Duration.ofSeconds(130)).GET().build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() >= 400) throw new RuntimeException("API status " + response.statusCode());
        System.out.println(response.body());
    }
}
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;

var apiKey = Environment.GetEnvironmentVariable("WSA_API_KEY")
    ?? throw new InvalidOperationException("Set WSA_API_KEY");
var target = Environment.GetEnvironmentVariable("TARGET_URL")
    ?? throw new InvalidOperationException("Set TARGET_URL");
var parameters = new Dictionary<string, string> {
    ["api_key"] = apiKey, ["url"] = target, ["timeout"] = "120000",
    ["js_instructions"] = await File.ReadAllTextAsync("instructions.json"),
};
var query = string.Join("&", parameters.Select(entry =>
    Uri.EscapeDataString(entry.Key) + "=" + Uri.EscapeDataString(entry.Value)));
using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(130) };
using var response = await client.GetAsync("https://api.webscrapingapi.com/v1?" + query);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
require 'json'
require 'net/http'
require 'uri'

instructions = JSON.parse(File.read('instructions.json'))
uri = URI('https://api.webscrapingapi.com/v1')
uri.query = URI.encode_www_form(
  api_key: ENV.fetch('WSA_API_KEY'), url: ENV.fetch('TARGET_URL'),
  timeout: 120000, js_instructions: JSON.generate(instructions)
)
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
http.open_timeout = 10
http.read_timeout = 130
response = http.get(uri.request_uri)
raise "API status #{response.code}" unless response.is_a?(Net::HTTPSuccess)
puts response.body

Response

Without json_response=1, a checkpoint-only request returns this JSON object. The example data strings below are placeholders for the actual image bytes:

{
  "screenshots": [
    { "name": "assessments", "mime_type": "image/jpeg", "data": "<base64>" },
    { "name": "sales_history", "mime_type": "image/jpeg", "data": "<base64>" },
    { "name": "taxes", "mime_type": "image/jpeg", "data": "<base64>" },
    { "name": "payments", "mime_type": "image/jpeg", "data": "<base64>" }
  ]
}

Entries retain instruction order and their supplied names. Each data field is raw base64 with no data:image/jpeg;base64, prefix. Decode it to obtain a JPEG.

With json_response=1, screenshots appears at the root of the existing JSON envelope; the usual body, headers, and metadata remain available. If you also set screenshot=1, the existing singular screenshot field still contains the final image captured after the instruction sequence. The checkpoint array is additional. Requests without screenshot actions keep their existing response format.

Limits and failures

  • A request may contain at most 10 screenshot actions, with unique names.
  • The combined length of all checkpoint data strings may not exceed 20 MiB (20,971,520 ASCII bytes). This is a limit on base64 output, not decoded image bytes. The optional final screenshot is separate from this checkpoint limit.
  • The request timeout (maximum and default 120000 ms) is one shared budget for navigation, instructions, and captures when screenshot actions are used. Adding a capture does not reset it. Allow extra time in the HTTP client to receive the response.
  • A capture failure, checkpoint output-limit failure, or request deadline fails the request; no successful partial screenshot collection is returned. Setting strict: "false" cannot suppress those errors.

Actual completion time depends on the target, its data loading, and image sizes. Measure your complete sequence before relying on four captures within the request budget. Element captures or viewport captures can reduce image size when full-page images are unnecessary.

On this page