---
title: "List Page Audit Scores"
method: GET
path: "/{brand_id}/audit-scores/pages"
tags: ["audit-scores"]
---

# List Page Audit Scores

`GET /{brand_id}/audit-scores/pages`

## Request

- Base URL: `https://api.scrunchai.com/v1`
- URL: `https://api.scrunchai.com/v1/{brand_id}/audit-scores/pages`
- Auth: HTTP bearer

The latest AI-visibility score per page for a brand — retrievability and citability, each page's `url`, when it was scored (`generated_at`), its headroom (open work by severity), and the sitemap page it maps to (`mapped_page_id`, null when unmatched).

Page through the whole brand with `limit` (max 1000) and `offset`. Ordered by page `url` (stable for pagination), not by score.

Pass `domain` (e.g. `us.example.com`) to scope to one site of the brand, and/or `path_prefix` (e.g. `/en-uk`) for a section or locale under a host; omit both for every audited page.

## Path parameters

- `brand_id` integer, required

## Query parameters

- `domain` string, nullable: Scope to one site of the brand by host, e.g. `us.example.com`.
- `path_prefix` string, nullable: Scope to a path prefix of the site, e.g. `/en-uk` for a locale section.
- `limit` integer
- `offset` integer

## Response `200`

Successful Response

- CollectionResponsePageScoreModel
  - `total` integer, required
  - `offset` integer
  - `limit` integer, nullable
  - `items` PageScoreModel[], required
    - `url` string, required
    - `model_version` string, required
    - `generated_at` string, date-time, required
    - `score` DisplayedScore, required: The two numbers we put on screen, both 0-100. citability is vs the winning page (50 = parity with it); the loser-side floor stays a diagnostic and isn't surfaced here.
      - `retrievability` number, required
      - `citability` number, required
    - `mapped_page_id` integer, nullable
    - `headroom` PageHeadroomModel: How much optimization work is still open on one page: a plain count of its surfaced opportunities, broken out by severity. Deliberately independent of the page's audit score. The score frames the goal as "get to 100", which is the framing this metric exists to replace — so headroom neither reads the score nor is capped against it. It answers "how much is there to do here", not "how far from perfect is this". Counts, not modeled point-gains: `expected_lift_pp` is a per-recommendation estimate, and summing several of them treats overlapping fixes as independent. A count makes no claim the data can't support. A page with no surfaced opportunity carries zeroes — nothing left to do. That differs from a page never audited, which has no headroom at all (see `PageScoreModel.headroom`).
      - `high` integer, required
      - `medium` integer, required
      - `low` integer, required
  - `metadata` TimeSeriesMetadata
    - `aggregation_granularity` 'daily' | 'weekly' | 'monthly', required
    - `period_count` integer, required: The number of periods in the time series
    - `start_date` string, date-time, required: The start date of the time series
    - `end_date` string, date-time, required: The end date of the time series
    - `top_domains` TopDomainsMetadata: Metadata about top domains, used by sources/domains endpoints.
      - `domains` TopDomainSummary[], required: Top domains by observation count (always domain-level aggregated)
        - `domain` string, required
        - `domain_owner` string, required
        - `observation_count` integer, required
      - `grand_total` integer, required: Total observation count across all domains (for calculating 'Other')
      - `owner_totals` object, required: Observation counts by owner type (brand, competitor, other)
      - `owner_time_series` OwnerTimeSeriesPoint[], nullable: Time series data by owner type for trend visualization
        - `time_bucket` string, required: Date string for the time bucket (YYYY-MM-DD)
        - `brand` integer, required: Observation count for brand-owned domains
        - `competitor` integer, required: Observation count for competitor-owned domains
        - `other` integer, required: Observation count for third-party domains
      - `segment_totals` SegmentTotal[]: Server-side observation counts per citation segment (covers all domains, not just top-N)
        - `name` string, required
        - `observation_count` integer, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-29** `a00f8154837e`: 2 info
  - added the new optional `query` request parameter `domain`
  - added the new optional `query` request parameter `path_prefix`
- **2026-08-26** `10f2a17e0cd2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scrunchai/apis/scrunch-data-api/changes/:brand_id/audit-scores/pages/get.md)

---

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