---
title: "List displays"
method: GET
path: "/displays"
tags: ["Displays"]
---

# List displays

`GET /displays`

## Request

- Base URL: `https://api.privy.com/v1`
- URL: `https://api.privy.com/v1/displays`
- Auth: HTTP bearer

Retrieve a paginated list of your on-site displays, newest first.
Archived displays are excluded by default — pass `status=archived` to list them.

The display inventory — use it to enumerate or count displays, since
`/v1/reports/displays` is a capped leaderboard that leaves out displays
with no activity. Configuration only: views, signups, and attributed
revenue come from `/v1/reports/displays` and
`/v1/reports/displays/{display_id}`. Rows carry no show triggers or
audience summary; `/v1/displays/{id}` adds those.

**Required scope:** `displays_read`

## Query parameters

- `page` integer
- `per_page` integer
- `status` 'draft' | 'scheduled' | 'live' | 'paused' | 'ended' | 'archived'

## Headers

- `Privy-Account-Id` string

## Response `200`

A paginated list of displays.

- object
  - `data` Display[]
    - `id` string: Stable, unique identifier for the display. Use this value in `/v1/displays/{id}`.
    - `title` string, nullable
    - `display_type` 'popup' | 'flyout' | 'banner' | 'bar' | 'spin_to_win' | 'embedded_form' | 'landing_page' | 'thank_you_page' | 'multi_display' | 'null', nullable: The display's on-site shape. `null` when the display's shape cannot be derived.
    - `goal` string, nullable: What the display is optimized for.
    - `status` 'draft' | 'scheduled' | 'live' | 'paused' | 'ended' | 'archived': - `draft` — creation not completed. - `scheduled` — completed, scheduled to start later. - `live` — running and enabled on the site. - `paused` — running window but disabled. - `ended` — schedule window has passed. - `archived` — archived by the merchant (excluded from the list unless `status=archived`).
    - `starts_at` string, date-time, nullable
    - `ends_at` string, date-time, nullable
    - `ab_test` object
      - `present` boolean
      - `state` string, nullable: State of the display's A/B test, when one exists.
    - `coupon` CouponRef: The coupon pool attached to a message or display — a `{{ coupon_code }}` tag in the content only renders when one is attached. Pass `id` to `GET /v1/coupons/{id}` for the pool's inventory and health; `kind` and `platform` match that endpoint's rows.
      - `id` string: The pool's identifier, as returned by `GET /v1/coupons`.
      - `title` string
      - `kind` 'master' | 'unique': `master` is a single shared code; `unique` is a pool of individually generated codes.
      - `platform` 'manual' | 'shopify' | 'bigcommerce' | 'woocommerce'
    - `created_at` string, date-time
  - `pagination` PaginationEnvelope
    - `page` integer
    - `per_page` integer
    - `total_count` integer
    - `total_pages` integer

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `422`: One or more fields failed validation.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `cf0885e90d5a`: 8 warning
  - added the new `forbidden` enum value to the `error/code` response property for the response status `401`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `403`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `422`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `429`
  - …4 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/displays/get.md)

---

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