---
title: "List Page Recommendations"
method: GET
path: "/{brand_id}/site-optimization/recommendations/by-page"
tags: ["site-optimization"]
---

# List Page Recommendations

`GET /{brand_id}/site-optimization/recommendations/by-page`

## Request

- Base URL: `https://api.scrunchai.com/v1`
- URL: `https://api.scrunchai.com/v1/{brand_id}/site-optimization/recommendations/by-page`
- Auth: HTTP bearer

List the latest recommendations per page for a brand — each page's AI-visibility scores, the recommendations to improve it (in the `opportunities` field), and what it already does well (`strengths`).

Pass one or more `path` params (e.g. `?path=/about&path=/pricing`) to scope to specific pages; omit them to page through every audited path. Paths are matched normalized (case-insensitive, trailing slash ignored). Each page returns only its most recent audit.

For a brand spanning several sites, each item carries its absolute `url` alongside `path`. Pass `domain` (e.g. `us.example.com`) to scope to one site, and/or `path_prefix` (e.g. `/en-uk`) for a locale or section under a host. Without them the list is brand-wide and two pages sharing a path across sites collapse onto one row.

## Path parameters

- `brand_id` integer, required

## Query parameters

- `path` string[], nullable: Restrict to these page paths. Repeat for multiple.
- `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: Maximum number of pages to return.
- `offset` integer: Number of pages to skip (pagination).

## Response `200`

Successful Response

- CollectionResponsePathDiagnostics
  - `total` integer, required
  - `offset` integer
  - `limit` integer, nullable
  - `items` PathDiagnostics[], required
    - `path` string, required
    - `url` string, required
    - `generated_at` string, date-time, required
    - `content_sha1` string, nullable
    - `model_version` string, required
    - `scores` PageScores, required: Page-level AI-visibility scores as percentages (0-100).
      - `retrievability` number, required
      - `citeability` number, required
    - `opportunities` DiagnosticOpportunity[]
      - `best_practice_id` string, nullable
      - `label` string, nullable
      - `bucket` 'hygiene' | 'transformation' | 'enrichment', required
      - `bucket_label` string, nullable
      - `recommended_change` string, required
      - `expected_lift_pp` number, required
      - `severity` 'low' | 'medium' | 'high', required
      - `heading_path` string[]
    - `strengths` DiagnosticStrength[]
      - `best_practice_id` string, nullable
      - `label` string, nullable
      - `message` string, required
      - `contribution_pp` number, required
      - `heading_path` string[]
    - `optimization_status` 'pending' | 'completed' | 'staged' | 'deployed' | 'retired' | 'outdated' | 'acknowledged', nullable
    - `acknowledged_at` string, date-time, nullable
  - `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`: 3 info
  - added the new optional `query` request parameter `domain`
  - added the new optional `query` request parameter `path_prefix`
  - added the required property `items/items/url` to the response with the `200` status
- **2026-09-17** `18ca42065270`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/scrunchai/apis/scrunch-data-api/changes/:brand_id/site-optimization/recommendations/by-page/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)