Skip to the content

localscreenshot Docs

/

Back to the site Dashboard

Screenshots

Run in the background

By default a request waits for its screenshot. Add async=true to get an id right away and read the result later. Use it for long pages, for batches, or when your own request must answer fast.

Start a screenshot

Send the same request as usual, with async=true. The answer is 202 with the screenshot in its first state.

Read the result

Read the address given in Location until status is succeeded or failed. Wait the number of seconds in Retry-After between two reads.

Status	What it means
`queued`	Waiting for a free browser.
`running`	The page is being loaded.
`succeeded`	Done. `image` holds the link.
`failed`	Done, without an image. `error` says why.

Reading a screenshot answers 200 whatever its status: look at status and error, not at the HTTP code.

When a normal request also answers 202

A request without async waits up to 50 seconds. If the screenshot is not finished by then, the answer is the same 202, with the same Location. The work is not lost: read it the same way.

Credits

The credits are reserved when the screenshot starts, and charged when it succeeds. A failed screenshot is not charged.
credits.charged is null while the screenshot is running, then says what it cost.
Screenshots in the background count toward the number you can run at once. See Credits and limits.

No webhooks yet. We do not call your server when a screenshot is done. Read the screenshot until it is finished.

NextFile formats

Start in the background

curl -X POST "https://api.localscreenshot.com/v1/screenshot" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.wikipedia.org",
    "full_page": true,
    "async": true
  }'

const response = await fetch("https://api.localscreenshot.com/v1/screenshot", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.LOCALSCREENSHOT_API_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    "url": "https://www.wikipedia.org",
    "full_page": true,
    "async": true
  }),
});
const data = await response.json();

import os
import requests

response = requests.post(
    "https://api.localscreenshot.com/v1/screenshot",
    json={
      "url": "https://www.wikipedia.org",
      "full_page": True,
      "async": True
    },
    headers={"Authorization": "Bearer " + os.environ["LOCALSCREENSHOT_API_KEY"]},
)
data = response.json()

<?php

$curl = curl_init("https://api.localscreenshot.com/v1/screenshot");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => json_encode(["url" => "https://www.wikipedia.org", "full_page" => true, "async" => true]),
    CURLOPT_HTTPHEADER => ["Authorization: Bearer ".getenv("LOCALSCREENSHOT_API_KEY"), "Content-Type: application/json"],
]);
$body = curl_exec($curl);
$data = json_decode($body, true);

202

HTTP/1.1 202 Accepted
Location: https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR
Retry-After: 2

The body

{
  "id": "01JABCDEF2G3H4J5K6M7N8P9QR",
  "status": "queued",
  "image": null,
  "page": null,
  "credits": { "charged": null, "reserved": 1, "remaining": 49 },
  "error": null,
  "links": { "self": "https://api.localscreenshot.com/v1/screenshots/01JABC..." }
}

Read it

curl "https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY"

const response = await fetch("https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR", {
  headers: { Authorization: `Bearer ${process.env.LOCALSCREENSHOT_API_KEY}` },
});
const data = await response.json();

import os
import requests

response = requests.get(
    "https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR",
    headers={"Authorization": "Bearer " + os.environ["LOCALSCREENSHOT_API_KEY"]},
)
data = response.json()

<?php

$curl = curl_init("https://api.localscreenshot.com/v1/screenshots/01JABCDEF2G3H4J5K6M7N8P9QR");
curl_setopt_array($curl, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer ".getenv("LOCALSCREENSHOT_API_KEY")],
]);
$body = curl_exec($curl);
$data = json_decode($body, true);