# 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`.

**Read a screenshot**

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

| 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](https://docs.localscreenshot.com/countries). |
| `credits` | Credits charged, reserved and left. |
| `error` | `null`, or the reason the screenshot failed. See [Errors](https://docs.localscreenshot.com/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.

**The image field**

```json
{
  "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 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.

**List, 50 at a time**

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

**200**

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

## 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.

**Delete a screenshot**

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