> ## Documentation Index > Fetch the complete documentation index at: https://help.privy.com/llms.txt > Use this file to discover all available pages before exploring further. # List display performance > 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` ## OpenAPI ````yaml openapi/privy-api.yaml GET /reports/displays openapi: 3.1.0 info: title: Privy API version: '1.0' description: > The Privy API lets you programmatically manage your contact list and read what you have set up in Privy. Create, update, unsubscribe, and remove contacts; report orders; and read your campaigns, flows, segments, orders, store products, coupon pools, performance reports, and account setup. servers: - url: https://api.privy.com/v1 description: Production security: - bearerAuth: [] tags: - name: Account description: Retrieve information about the authenticated Privy account. - name: Contacts description: Manage your contact list. - name: Imports description: >- Read your contact import history — CSV uploads, connected-provider syncs, and SMS consent imports. - name: Campaigns description: >- Read your message campaigns — email and SMS newsletters, plus the messages your flows send. - name: Displays description: >- Read your on-site displays (popups, flyouts, banners, embedded forms, landing pages). - name: Coupons description: Read your coupon pools, their code inventory, and individual codes. - name: Reports description: >- Read performance reporting — signups, views, conversion rates, and attributed revenue — for your business, displays, and flows. - name: Flows description: Read your automation flows and their configuration. - name: Segments description: Read your customer segments and their membership. - name: Orders description: Report orders placed in your store and read your order history. - name: Products description: Read the product catalog and collections of your connected store. - name: Events description: Ingest custom events to trigger Flows and other automations. paths: /reports/displays: get: tags: - Reports summary: List display performance description: | 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` operationId: listDisplayReports parameters: - $ref: '#/components/parameters/AccountIdParam' - $ref: '#/components/parameters/ReportPeriodParam' - $ref: '#/components/parameters/ReportStartDateParam' - $ref: '#/components/parameters/ReportEndDateParam' - name: sort in: query description: The metric to rank displays by, best first. schema: type: string enum: - signups - signup_rate - views - revenue - orders default: signups example: signups - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/PerPageParam' responses: '200': description: Displays ranked by the requested sort, with the resolved period. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/DisplayReportRow' period: $ref: '#/components/schemas/ReportPeriod' pagination: $ref: '#/components/schemas/PaginationEnvelope' example: data: - display_id: gk2P8Zw1Lq title: Summer Sale Popup display_type: popup status: live published_date: '2026-06-01' stats: views: value: 4200 unit: count signups: value: 310 unit: count signup_rate: value: 7.4 unit: percent attributed_orders: value: 28 unit: count attributed_revenue: value: 1840.5 unit: usd period: label: last_30_days start_date: '2026-06-21' end_date: '2026-07-20' pagination: page: 1 per_page: 40 total_count: 1 total_pages: 1 '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/InsufficientScope' '422': $ref: '#/components/responses/ValidationFailed' '429': $ref: '#/components/responses/RateLimited' security: - bearerAuth: [] components: parameters: AccountIdParam: name: Privy-Account-Id in: header required: false description: > Target a subaccount instead of the main connected account. Pass a subaccount `id` from get_account's `subaccounts` list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself. schema: type: string example: S1U2B3A4C5C6T7 ReportPeriodParam: name: period in: query description: >- The date range to report over, resolved in the account's time zone. Pass `custom` together with `start_date` and `end_date`. schema: type: string enum: - last_7_days - last_30_days - last_90_days - this_month - last_month - custom default: last_30_days example: last_30_days ReportStartDateParam: name: start_date in: query description: >- Inclusive start of a `custom` period (ISO 8601 date). Required when `period=custom`, ignored otherwise. schema: type: string format: date example: '2026-06-01' ReportEndDateParam: name: end_date in: query description: >- Inclusive end of a `custom` period (ISO 8601 date). Required when `period=custom`, ignored otherwise. Custom periods are capped at 366 days. schema: type: string format: date example: '2026-06-30' PageParam: name: page in: query description: Page number (starts at 1). schema: type: integer default: 1 minimum: 1 example: 1 PerPageParam: name: per_page in: query description: >- Number of results per page. Values outside 10–100 are clamped to the nearest bound. schema: type: integer default: 40 minimum: 10 maximum: 100 example: 40 schemas: DisplayReportRow: type: object description: >- One display's entry in the ranked leaderboard. `GET /v1/reports/displays/{display_id}` returns the richer `DisplayReportDetail` shape for a single display. properties: display_id: type: string description: >- The display's unique identifier. Use this value in `/v1/reports/displays/{display_id}` and `/v1/displays/{id}`. example: gk2P8Zw1Lq title: type: - string - 'null' description: The display's name. `null` when the merchant never named it. example: Summer Sale Popup display_type: type: - string - 'null' description: >- The display's on-site shape (e.g. `popup`, `flyout`, `banner`, `bar`, `embedded_form`, `landing_page`). example: popup status: type: string description: >- The display's lifecycle status (e.g. `draft`, `scheduled`, `live`, `paused`, `ended`, `archived`). example: live published_date: type: - string - 'null' format: date description: >- The date the display started showing, in the account's time zone. `null` when it has never been published. example: '2026-06-01' stats: $ref: '#/components/schemas/DisplayReportStats' ReportPeriod: type: object description: | 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. properties: label: type: string enum: - last_7_days - last_30_days - last_90_days - this_month - last_month - custom example: last_30_days start_date: type: string format: date example: '2026-06-21' end_date: type: string format: date example: '2026-07-20' PaginationEnvelope: type: object properties: page: type: integer example: 1 per_page: type: integer example: 25 total_count: type: integer example: 142 total_pages: type: integer example: 6 DisplayReportStats: type: object description: | 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. properties: views: $ref: '#/components/schemas/ReportMetric' signups: $ref: '#/components/schemas/ReportMetric' signup_rate: $ref: '#/components/schemas/ReportMetric' attributed_orders: $ref: '#/components/schemas/ReportMetric' attributed_revenue: $ref: '#/components/schemas/ReportMetric' ErrorResponse: type: object properties: error: type: object required: - code - message properties: code: type: string enum: - invalid_client - invalid_scope - unauthorized - insufficient_scope - paid_plan_required - api_access_required - not_found - no_connected_store - conflict - contacts_not_ready - validation_failed - rate_limited - store_unavailable example: validation_failed message: type: string example: One or more fields are invalid details: type: array items: type: object properties: field: type: string example: email message: type: string example: is required ReportMetric: type: object description: | 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. properties: value: type: number example: 42 unit: type: string description: '`count`, `percent`, or a lowercased ISO 4217 currency code.' example: count responses: Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Bearer token is missing or invalid InsufficientScope: description: Token lacks the required scope for this endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_scope message: Token does not have the required scope ValidationFailed: description: One or more fields failed validation. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: validation_failed message: One or more fields are invalid details: - field: email message: is required RateLimited: description: Rate limit exceeded. Retry after the specified time. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer example: 42 X-RateLimit-Limit-Minute: description: Maximum requests allowed per minute. schema: type: integer example: 60 X-RateLimit-Remaining-Minute: description: Requests remaining in the current minute window. schema: type: integer example: 0 X-RateLimit-Reset-Minute: description: Unix timestamp when the minute window resets. schema: type: integer example: 1711929600 X-RateLimit-Limit-Day: description: Maximum requests allowed per day. schema: type: integer example: 10000 X-RateLimit-Remaining-Day: description: Requests remaining in the current day window. schema: type: integer example: 9500 X-RateLimit-Reset-Day: description: Unix timestamp when the day window resets. schema: type: integer example: 1712016000 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limited message: Rate limit exceeded securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API token or OAuth access token description: > Send either an API token or an OAuth access token as `Authorization: Bearer `. See the Authentication page for details. ````