Skip to main content
POST
/
api
/
v1
/
screenshot
Screenshot webpage
curl --request POST \
  --url https://app.dumplingai.com/api/v1/screenshot \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "https://example.com",
  "fullPage": true,
  "viewport": {
    "width": 1280,
    "height": 720
  },
  "wait": 1000
}
'
import requests

url = "https://app.dumplingai.com/api/v1/screenshot"

payload = {
"url": "https://example.com",
"fullPage": True,
"viewport": {
"width": 1280,
"height": 720
},
"wait": 1000
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
url: 'https://example.com',
fullPage: true,
viewport: {width: 1280, height: 720},
wait: 1000
})
};

fetch('https://app.dumplingai.com/api/v1/screenshot', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://app.dumplingai.com/api/v1/screenshot",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'url' => 'https://example.com',
'fullPage' => true,
'viewport' => [
'width' => 1280,
'height' => 720
],
'wait' => 1000
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://app.dumplingai.com/api/v1/screenshot"

payload := strings.NewReader("{\n \"url\": \"https://example.com\",\n \"fullPage\": true,\n \"viewport\": {\n \"width\": 1280,\n \"height\": 720\n },\n \"wait\": 1000\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://app.dumplingai.com/api/v1/screenshot")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"url\": \"https://example.com\",\n \"fullPage\": true,\n \"viewport\": {\n \"width\": 1280,\n \"height\": 720\n },\n \"wait\": 1000\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://app.dumplingai.com/api/v1/screenshot")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"url\": \"https://example.com\",\n \"fullPage\": true,\n \"viewport\": {\n \"width\": 1280,\n \"height\": 720\n },\n \"wait\": 1000\n}"

response = http.request(request)
puts response.read_body
{
  "screenshotUrl": "<string>"
}
{
"error": "<string>"
}
{
"error": "<string>"
}

Description

This endpoint captures a screenshot of a specified URL, with options to customize the viewport, block cookie banners, set a wait time before capturing, and more.

Endpoint

POST https://app.dumplingai.com/api/v1/screenshot

Headers

  • Content-Type: application/json
  • Authorization: Bearer <API_KEY> (required)

Request Body

{
  "url": "string", // Required. The URL to capture.
  "fullPage": "boolean", // Optional. Whether to capture the full page. Default: false.
  "viewport": {
    // Optional. The viewport dimensions. Default: { width: 1024, height: 1024 }
    "width": "number",
    "height": "number"
  },
  "clipRectangle": {
    // Optional. The area of the screen to clip. fullPage must be false to use this. Defaults to viewport.
    "top": "number",
    "left": "number",
    "width": "number",
    "height": "number"
  },
  "blockCookieBanners": "boolean", // Optional. Whether to block cookie banners. Default: true.
  "wait": "number", // Optional. Time to wait before capture in ms. Max: 5000. Default: 0.
  "autoScroll": "boolean" // Optional. Whether to automatically scroll the page (e.g. for lazy loaded images). Default: false.
}

Responses

Success (200)

Returns the screenshot data and related information.
{
  "screenshotUrl": "string" // URL of the captured screenshot
}
  • Content-Type: application/json
  • X-RateLimit-Limit: The rate limit for the user.
  • X-RateLimit-Remaining: The remaining number of requests for the user.

Bad Request (400)

Returned if the request is invalid.
{
  "error": "Error message describing the issue"
}

Internal Server Error (500)

Returned if there’s an error during the screenshot process.
{
  "error": "Failed to screenshot: [error message]"
}

Example Request

curl -X POST https://app.dumplingai.com/api/v1/screenshot \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
  "url": "https://example.com",
  "fullPage": true,
  "viewport": {
    "width": 1920,
    "height": 1080
  },
  "blockCookieBanners": true,
  "wait": 1000,
  "autoScroll": true
}'

Example Response

{
  "screenshotUrl": "https://storage.example.com/screenshots/abcdef123456.png"
}

Notes

  • The viewport width must be less than or equal to 3840 pixels, and the height must be less than or equal to 10240 pixels.
  • The maximum wait time is 5000 milliseconds (5 seconds).
  • Credit usage:
    • Base cost: 20 credits
    • Additional 10 credits if autoScroll is true
    • Additional 10 credits if wait is set (any non-zero value)
  • If the URL doesn’t include a protocol, https:// will be used by default.
  • The clipRectangle option can only be used when fullPage is set to false.
  • Usage is recorded with detailed parameters for each request.
  • Events may be logged to PostHog for analytics purposes if enabled.

Rate Limiting

Rate limit headers (X-RateLimit-Limit and X-RateLimit-Remaining) are included in the response to indicate the user’s current rate limit status.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Options for capturing a screenshot of a webpage.

url
string<uri>
required

Fully-qualified URL to capture.

fullPage
boolean
default:false

Capture the entire scrollable page.

viewport
object

Browser viewport size in pixels.

clipRectangle
object

Clipping rectangle when capturing a partial screenshot.

Attempt to hide cookie banners before capturing the screenshot.

wait
integer
default:0

Delay in milliseconds before capturing, allowing the page to finish loading.

Required range: 0 <= x <= 5000
autoScroll
boolean
default:false

Scroll the page to trigger lazy-loaded content before capturing.

requestSource
enum<string>

Optional identifier describing where the API request originated.

Available options:
API,
WEB,
MAKE_DOT_COM,
ZAPIER,
N8N,
PLAYGROUND,
DEFAULT_AUTOMATION,
AGENT_PREVIEW,
AGENT_LIVE,
AUTOPILOT,
STUDIO

Response

Screenshot data returned.

screenshotUrl
string<uri>
required

Temporary download URL for the generated screenshot.