---
title: "List display performance"
method: GET
path: "/reports/displays"
tags: ["Reports"]
---

# List display performance

`GET /reports/displays`

## Request

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

Rank your displays by performance over a period — signups by default,
or any of the documented sort keys. Displays whose value for the chosen
sort key is zero are left out entirely, and ranking stops at 50
displays, which also caps the reported `total_count`. Use
`/v1/reports/displays/{display_id}` for one display's full stat set,
including average order value and A/B test results.

**Required scope:** `reports_read`

## Query parameters

- `period` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'this_month' | 'last_month' | 'custom'
- `start_date` string, date
- `end_date` string, date
- `sort` 'signups' | 'signup_rate' | 'views' | 'revenue' | 'orders'
- `page` integer
- `per_page` integer

## Headers

- `Privy-Account-Id` string

## Response `200`

Displays ranked by the requested sort, with the resolved period.

- object
  - `data` DisplayReportRow[]
    - `display_id` string: The display's unique identifier. Use this value in `/v1/reports/displays/{display_id}` and `/v1/displays/{id}`.
    - `title` string, nullable: The display's name. `null` when the merchant never named it.
    - `display_type` string, nullable: The display's on-site shape (e.g. `popup`, `flyout`, `banner`, `bar`, `embedded_form`, `landing_page`).
    - `status` string: The display's lifecycle status (e.g. `draft`, `scheduled`, `live`, `paused`, `ended`, `archived`).
    - `published_date` string, date, nullable: The date the display started showing, in the account's time zone. `null` when it has never been published.
    - `stats` DisplayReportStats: Performance metrics for one display over the report period. `views` counts impressions — one per time the display loaded on a visitor's screen, so a visitor who saw it on three pages counts three times — and `signups` counts form submissions, not distinct contacts. `signup_rate` is `signups` over `views`. `attributed_orders` and `attributed_revenue` credit the display under the same last-touch rule as the rest of Privy's reporting: an order counts when the contact's most recent engagement in the 7 days before it was an open or click on a message this display sends, such as its follow-up email or SMS. They are not a count of visitors who signed up here and later bought, which is the figure Privy's own display reporting shows — expect the two to differ, and expect a display that sends no follow-up message to report zero.
      - `views` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `signups` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `signup_rate` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `attributed_orders` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
      - `attributed_revenue` ReportMetric: A single report metric with its unit. `count` values are whole numbers, `percent` values are 0–100 with one decimal. Money metrics carry the account's lowercased ISO 4217 currency code as their unit (e.g. `usd`, `eur`, `jpy`) and are expressed in that currency's major units, two decimals. A rate whose denominator was zero reports 0, not null — so 0 does not distinguish "no activity" from "activity that never converted"; read the underlying counts to tell those apart.
        - `value` number
        - `unit` string: `count`, `percent`, or a lowercased ISO 4217 currency code.
  - `period` ReportPeriod: The resolved date range the report covers, inclusive, in the account's time zone. Every label except `last_month` ends today, so the last day of the range is still in progress: `last_7_days` is the six days before today plus today, `this_month` runs from the 1st through today, and `last_month` is the whole previous calendar month. Custom ranges cannot exceed 366 days.
    - `label` 'last_7_days' | 'last_30_days' | 'last_90_days' | 'this_month' | 'last_month' | 'custom'
    - `start_date` string, date
    - `end_date` string, date
  - `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/reports/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)