Skip to the content

localscreenshot Docs

/

Back to the site Dashboard

Screenshots

Read a screenshot

Every screenshot has an id. Use it to read the screenshot again, get a fresh link to its image, list what you took, or delete it.

Read one

GET/v1/screenshots/{id}

Returns the screenshot as JSON: its status, its image, what the page answered, and the credits it used. The id is in the X-Screenshot-Id header of the answer that took it, and in the id field with response=json.

Field	Description
`status`	`queued`, `running`, `succeeded` or `failed`.
`image`	The file: a link, its type, size and dimensions. `null` until the screenshot has succeeded.
`page`	What the page answered: status, final address after redirects, title.
`country`	Only when you asked for a country: the one requested and the one observed.
`attestation`	Only when you asked for a country: the signed technical attestation. See Countries and attestation.
`credits`	Credits charged, reserved and left.
`error`	`null`, or the reason the screenshot failed. See Errors.

A screenshot you do not own, or one that was deleted, answers not_found.

The link to the image

image.url is a signed link. It opens without your API key, so you can hand it to a browser or to another tool.

The link works for 15 minutes. Read the screenshot again to get a fresh one.
The image itself is kept for 7 days. image.available_until says until when. After that the file is destroyed and only the record of the screenshot remains.
Download the image if you need it longer.

List your screenshots

GET/v1/screenshots

Returns your screenshots, newest first, by pages.

Parameter	Description
`limit`	How many to return, 1 to 100. Default: 20.
`cursor`	The `next_cursor` of the previous page.

next_cursor is null on the last page. Deleted screenshots are not listed.

Delete one

DELETE/v1/screenshots/{id}

Deletes a screenshot. It answers 204 with no body.

The image and its details are destroyed, and its links stop working.
A screenshot that is still running is cancelled and not charged.
Credits already used are not given back.
Deleting the same screenshot twice answers 204 both times.

NextRun in the background

Read a screenshot

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);

The image field

{
  "url": "https://api.localscreenshot.com/v1/screenshots/01JABC.../image?expires=...&signature=...",
  "mime": "image/png",
  "bytes": 83672,
  "width": 1440,
  "height": 900,
  "pages": null,
  "sha256": "a5b9081b8430...",
  "truncated": false,
  "available_until": "2026-10-15T10:47:02Z"
}

List, 50 at a time

curl "https://api.localscreenshot.com/v1/screenshots?limit=50" \
  -H "Authorization: Bearer $LOCALSCREENSHOT_API_KEY"

const params = new URLSearchParams({
  "limit": "50"
});
const response = await fetch(`https://api.localscreenshot.com/v1/screenshots?${params}`, {
  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",
    params={
      "limit": "50"
    },
    headers={"Authorization": "Bearer " + os.environ["LOCALSCREENSHOT_API_KEY"]},
)
data = response.json()

<?php

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

200

{
  "data": [
    { "id": "01JABCDEF2G3H4J5K6M7N8P9QR", "status": "succeeded", "image": { "url": "...", "mime": "image/png" } }
  ],
  "next_cursor": "eyJjcmVhdGVkX2F0Ijoi..."
}

Delete a screenshot

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

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

import os
import requests

response = requests.delete(
    "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_CUSTOMREQUEST => "DELETE",
    CURLOPT_HTTPHEADER => ["Authorization: Bearer ".getenv("LOCALSCREENSHOT_API_KEY")],
]);
$body = curl_exec($curl);
$data = json_decode($body, true);