---
title: "Retrieve Paywall Preview Images"
method: GET
path: "/v2/paywalls/{id}/preview-images"
tags: ["Paywalls V2"]
---

# Retrieve Paywall Preview Images

`GET /v2/paywalls/{id}/preview-images`

Returns the capture session and generated images for the paywall's current document URL, starting or retrying the capture when needed. Use `force=true` to discard a completed capture and render it again. Requires paywalls:read scope.

## Path parameters

- `id` string, required

## Query parameters

- `country` string — Two-letter country override (for example GB) for user/device conditions. Does not convert catalog prices into another currency.
- `locale` string — Language or language-region for browser/device locale and price formatting, for example en-GB. Defaults to en-COUNTRY when country is specified. Does not supply translated paywall copy.
- `intro` 'eligible' | 'ineligible' — Override introductory-offer eligibility. Omit to retain the existing preview default.
- `force` 'true' | 'false' — Re-capture the current paywall document even when stored images already exist

## Response `200`

Success

- object
  - `render_context` object
    - `country` string — Two-letter country override (for example GB) for user/device conditions. Does not convert catalog prices into another currency.
    - `locale` string — Language or language-region for browser/device locale and price formatting, for example en-GB. Defaults to en-COUNTRY when country is specified. Does not supply translated paywall copy.
    - `intro` 'eligible' | 'ineligible' — Override introductory-offer eligibility. Omit to retain the existing preview default.
  - `branch_dimensions` string[] — Dimensions referenced by document conditions. Null means unavailable (pending or code-first runtime without condition metadata); an empty array means no supported dimensions were found. Request only the contexts you need; combinations are not generated automatically.
  - `object` 'paywall_preview_session', required
  - `id` string, required — Stable capture session ID
  - `paywall_id` string, required
  - `url` string, required — Immutable paywall document URL being captured
  - `status` 'pending' | 'running' | 'ready' | 'failed', required
  - `stage` 'queued' | 'fetching_paywall' | 'launching_browser' | 'awaiting_ping' | 'capturing_pages' | 'uploading' | 'done', required
  - `page_count` number, nullable, required
  - `pages` object[], required
    - `kind` 'page' | 'overlay' — Overlay frames show an exit/abandon sheet over its host page.
    - `host_page_node_id` string
    - `overlay_node_id` string
    - `page_index` number, required — Page index in the paywall document
    - `page_node_id` string, nullable, required — Stable editor node ID for the page, when available
    - `page_name` string, nullable, required — Editor-authored page name, when available
    - `flow_position` number, nullable, required — Position in the evaluated paywall route
    - `url` string, required — Public URL of the captured PNG
    - `width` number, required — Image width in pixels
    - `height` number, required — Image height in pixels
    - `captured_at` string, required — ISO 8601 capture timestamp
  - `apple_review_image` object, nullable, required
    - `url` string, required — Public URL of the Apple review PNG
    - `width` number, required — Image width in pixels
    - `height` number, required — Image height in pixels
    - `page_index` number, required — Paywall page rendered for the Apple review image
    - `captured_at` string, required — ISO 8601 capture timestamp
  - `error` object, nullable, required
    - `reason` 'no_ping' | 'paywall_fetch_failed' | 'browser_error' | 'upload_failed' | 'unknown', required
    - `message` string, required
    - `attempts` number, required
    - `retryable` boolean, required
  - `attempts` number, required
  - `created_at` string, required
  - `updated_at` string, required
  - `diagnostics` string[], required

## Other responses

- `400` — The request did not match the expected schema | The request was invalid or malformed
- `401` — No API key was provided in the request | The API key does not have a valid format | The API key is invalid or has been revoked | An error occurred while validating the API key | The session cookie is invalid or expired
- `403` — The API key does not have permission to perform this action
- `404` — The requested resource was not found
- `429` — Too many requests have been made in a short period
- `500` — An unexpected error occurred on the server
- `503` — A required service or security control could not be verified

## Changes

- **2026-09-16** `a01b83699803` — 8 info
  - added the new optional `query` request parameter `country`
  - added the new optional `query` request parameter `intro`
  - added the new optional `query` request parameter `locale`
  - added the optional property `branch_dimensions` to the response with the `200` status
  - …4 more
- **2026-09-09** `217c96dc9a29` — 21 breaking, 151 info
  - the `code` response's property type changed from `string` to no type for status `403`
  - the `code` response's property type changed from `string` to no type for status `404`
  - the `code` response's property type changed from `string` to no type for status `429`
  - the `code` response's property type changed from `string` to no type for status `500`
  - …168 more
  - …this revision’s changelog is incomplete
- **2026-09-04** `7dbbee8e0305` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/superwall/apis/superwall-api-v2/changes/v2/paywalls/:id/preview-images/get.md)

---

[API](https://skmtc.dev/superwall/apis/superwall-api-v2.md) · [All operations](https://skmtc.dev/superwall/apis/superwall-api-v2/llms.txt) · [OpenAPI document](https://skmtc.dev/superwall/apis/superwall-api-v2/revisions/bfb85c07a3d3?raw)