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
}
}| Field | Required | Description |
|---|---|---|
action | Yes | screenshot. |
name | Yes | Unique within the request. Use 1–64 ASCII letters, digits, underscores, or hyphens: [A-Za-z0-9_-]. |
options | No | Screenshot configuration object. Omit it to capture the current viewport. |
options.full_page | No | JSON boolean. Set true to capture the full page. |
options.width, options.height | No | Temporarily 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_selector | No | Nonempty CSS selector for the element to capture. Cannot be combined with full_page: true. |
timeout | No | Maximum 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.bodyResponse
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
datastrings may not exceed 20 MiB (20,971,520 ASCII bytes). This is a limit on base64 output, not decoded image bytes. The optional finalscreenshotis 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.