---
title: "List run screenshots"
method: GET
path: "/v1/runs/{run_id}/screenshots"
tags: ["runs"]
---

# List run screenshots

`GET /v1/runs/{run_id}/screenshots`

Scope: `runs:read`. Free. The model-input frames for a run, oldest first — the exact images the agent saw before each decision, which is what you want when reconstructing why it did something. Captured for every run, managed and BYOK alike.

Metadata only by default: a single frame is several hundred KB of base64, so pass `include_image=true` to inline `image_b64` (page size is clamped to 10 in that mode, and the response is `Cache-Control: no-store` because frames can show whatever was on screen).

Page with `after_index`. `index` is flat and monotonic across the WHOLE run and is the stable address for a frame: a run that was reaped and retried starts a new attempt whose `step` counter restarts at 1, so `step` alone is not unique — `attempt` tells you which try a frame belongs to. A frame whose stored bytes cannot be decoded is returned with `image_unavailable: true` rather than failing the page.

## Query parameters

- `limit` integer
- `after_index` integer
- `include_image` boolean

## Response `200`

A page of run screenshots.

- ListRunScreenshotsResponse
  - `object` 'list', required
  - `data` RunScreenshot[], required
    - `index` integer, required — Flat, monotonic position across the whole run. The stable address for a frame: `step` restarts at 1 on a retried attempt, so it is not unique on its own.
    - `attempt` integer, required — Which execution attempt produced this frame (1, 2, 3…). A run that was reaped and reclaimed has more than one.
    - `step` integer, required — Step number within that attempt.
    - `taken_at` string, date-time, nullable
    - `width` integer — Model coordinate-space width — what the agent's clicks were computed against, not necessarily the machine's physical resolution.
    - `height` integer
    - `mime_type` string
    - `size_bytes` integer — Plaintext frame size.
    - `sha256` string, nullable — SHA-256 of the plaintext frame, for dedup and integrity.
    - `degraded` boolean — True when capture failed and the agent had to act on a reused or placeholder frame.
    - `encrypted_at_rest` boolean
    - `image_b64` string, nullable — Base64 PNG. Present only with include_image=true.
    - `image_unavailable` boolean, nullable — Set instead of image_b64 when a stored frame could not be decoded. One bad frame never fails the page.
  - `has_more` boolean
  - `request_id` string

## Other responses

- `400` — Invalid request body or parameters.
- `401` — Missing, invalid, or revoked API key. Pass `X-API-Key: sk-coasty-live-...` (or test).
- `403` — API key lacks the required scope or tier-feature is unavailable on the caller's plan.
- `404` — Resource not found in this key's namespace.
- `409` — The resource state conflicts with this operation.
- `413` — The request body exceeds the endpoint limit.
- `422` — The JSON shape is valid but one or more values violate the endpoint contract.
- `429` — Rate or concurrency limit exceeded.
- `500` — Unexpected server error. Retry with exponential backoff.
- `502` — An upstream dependency returned an invalid response.
- `503` — A required service is temporarily unavailable.
- `504` — An upstream dependency timed out.

---

[API](https://skmtc.net/coasty/apis/coasty-public-api.md) · [All operations](https://skmtc.net/coasty/apis/coasty-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/coasty/coasty-public-api/revisions/f50d93b0d8a1/schema)