---
title: "Retrieve Visibility Overview"
method: GET
path: "/v1/visibility/overview"
tags: ["Visibility"]
---

# Retrieve Visibility Overview

`GET /v1/visibility/overview`

## Request

- Base URL: `https://api.lightsage.com`
- URL: `https://api.lightsage.com/v1/visibility/overview`
- Auth: API key in header `X-Lightsage-Api-Key`

Returns the visibility overview for the organization.

The response contains an aggregate `snapshot`, a daily visibility
`timeseries`, per-platform visibility and citation series in `by_platform`,
and a `competitors` comparison. Values are calculated from currently active
prompts. When the selected range has no prompt-run data, snapshot values are
`null` and `has_data` is `false`.

## Query parameters

- `start_date` string, date
- `end_date` string, date

## Response `200`

Successful Response

- PublicVisibilityOverviewResponse
  - `company` PublicCompany, required
    - `name` string, required
    - `domain` string, nullable
    - `logo_url` string, nullable
    - `relationship` string, nullable: The company relationship: `primary` for the organization's own company or `competitor` for a tracked competitor.
  - `date_range` PublicVisibilityDateRange, required
    - `start_date` string, required
    - `end_date` string, required
    - `granularity` string
    - `latest_run_date` string, nullable
    - `active_prompts_only` boolean
  - `has_data` boolean, required
  - `snapshot` PublicVisibilitySnapshot, required
    - `recommendation_score` number, nullable: Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings › Navigation.
    - `recommendation_score_rank` integer, nullable
    - `visibility_score` number, nullable: Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded.
    - `visibility_score_rank` integer, nullable
    - `share_of_voice` number, nullable: The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`.
    - `share_of_voice_rank` integer, nullable: Rank by `share_of_voice` among tracked companies, highest first.
    - `average_position` number, nullable: Mean mention position in AI responses; 1 is first and lower is better.
    - `average_position_rank` integer, nullable
    - `total_citations` integer: Owned-domain citations across all platforms; 0, not `null`, with no prompt runs.
  - `timeseries` PublicVisibilityTimeseries, required
    - `recommendation_score` PublicSeriesPoint[]: Company recommendation score per day. Empty unless the organization turns on Recommendation Score under Settings › Navigation.
      - `date` string, required: Only dates with prompt runs appear, so a series can be shorter than the range.
      - `value` number, nullable
    - `visibility_score` PublicSeriesPoint[]: Company visibility score per day: the share of prompt runs that mention the company (0 to 1).
      - `date` string, required: Only dates with prompt runs appear, so a series can be shorter than the range.
      - `value` number, nullable
  - `by_platform` PublicVisibilityByPlatform, required
    - `platforms` PublicPlatformRef[]
      - `platform_id` string, required
      - `name` string, required
      - `icon_url` string, nullable
      - `mention_count` integer: Prompt runs where the company was mentioned on this platform in the date range.
      - `prompt_run_count` integer: Total prompt runs on this platform in the date range.
    - `recommendation_score` object: Recommendation score series keyed by `platform_id`. Empty unless the organization turns on Recommendation Score under Settings › Navigation.
    - `visibility_score` object: Visibility score series keyed by `platform_id`: the share of that platform's prompt runs each day that mention the company (0 to 1).
    - `citations` object: Owned-domain citation counts keyed by platform_id.
  - `competitors` PublicCompetitorRow[]: Includes the primary company.
    - `company` PublicCompany, required
      - `name` string, required
      - `domain` string, nullable
      - `logo_url` string, nullable
      - `relationship` string, nullable: The company relationship: `primary` for the organization's own company or `competitor` for a tracked competitor.
    - `recommendation_score` number, nullable: Mean recommendation strength across successful prompt runs, from 0 to 1. Each run contributes the company's recommendation strength (0 to 1) when it is mentioned and 0 when it is not. Failed provider runs are excluded. `null` unless the organization turns on Recommendation Score under Settings › Navigation. Rows do not sum to 1.
    - `recommendation_score_rank` integer, nullable
    - `visibility_score` number, nullable: Fraction of successful prompt runs that mention the company, from 0 to 1; for example, 0.25 means one in four runs. Failed provider runs are excluded. A run can mention several companies, so rows do not sum to 1.
    - `visibility_score_rank` integer, nullable
    - `share_of_voice` number, nullable: The company's share of all mentions of tracked companies (your company plus configured competitors) in the same prompt runs, from 0 to 1; tracked companies add up to 1. Each company counts once per run. `null` for companies you do not track. Not the `share_of_voice` field removed in October 2026, which held the mention rate now returned as `visibility_score`.
    - `share_of_voice_rank` integer, nullable: Rank by `share_of_voice` among tracked companies, highest first.
    - `average_position` number, nullable: Mean mention position in AI responses; 1 is first and lower is better. 0 when never mentioned.
    - `average_position_rank` integer, nullable: Companies with an `average_position` of 0 rank last.
  - `period` PublicResolvedPeriod
    - `name` string, nullable: The `period` requested, or null when the range came from `start_date` and `end_date`.
    - `start_date` string, required: First day of the period (UTC), inclusive.
    - `end_date` string, required: Last day of the period (UTC), inclusive.
    - `days` integer, required: Days in the period, counting both ends.
    - `previous_start_date` string, required: First day of the previous period it is compared with.
    - `previous_end_date` string, required: Last day of the previous period. While a calendar week, month, or quarter is in progress, the previous one is cut to the same number of days.
    - `previous_days` integer, required: Days in the previous period.
    - `partial` boolean, required: Whether the period includes today, so its last day is still in progress.
    - `timezone` 'UTC'
  - `coverage` PublicCoverage
    - `comparable` boolean, required: Whether totals can be compared between the two periods. False when either period has a missing or short day or runs per day differ by more than 20%; compare per-run rates instead.
    - `notes` string[]: Why the periods are not comparable, in plain sentences.
    - `current` PublicPeriodCoverage, required
      - `start_date` string, required
      - `end_date` string, required
      - `runs` integer, required
      - `expected_runs` integer, required
      - `complete_days` integer, required: Days in the period other than today in progress.
      - `runs_per_day` number, nullable: Runs per complete day.
      - `missing_days` string[]
      - `short_days` string[]
    - `previous` PublicPeriodCoverage, required
      - `start_date` string, required
      - `end_date` string, required
      - `runs` integer, required
      - `expected_runs` integer, required
      - `complete_days` integer, required: Days in the period other than today in progress.
      - `runs_per_day` number, nullable: Runs per complete day.
      - `missing_days` string[]
      - `short_days` string[]
    - `days` PublicCoverageDay[]
      - `date` string, required
      - `period` 'current' | 'previous', required
      - `runs` integer, required: Successful prompt runs of active prompts that day.
      - `expected_runs` integer, required: Median daily runs over the 7 days before; 0 when no daily runs are expected.
      - `status` 'ok' | 'short' | 'missing' | 'in_progress' | 'not_expected', required: `missing`: no runs on a day that expected some. `short`: under half the expected runs. `in_progress`: today, before its runs finished.
  - `rates` PublicRates
    - `headline_metric` 'owned_citations' | 'owned_citations_per_run', required: The number to lead with: owned citations when the periods are comparable, otherwise owned citations per run.
    - `current` PublicPeriodRates, required
      - `runs` integer, required
      - `owned_citations` integer, required: Citations of the organization's own domains.
      - `owned_citations_per_run` number, nullable
      - `brand_mention_runs` integer, required: Runs that mention the primary company.
      - `mention_rate` number, nullable: Share of runs that mention the primary company, from 0 to 1.
    - `previous` PublicPeriodRates, required
      - `runs` integer, required
      - `owned_citations` integer, required: Citations of the organization's own domains.
      - `owned_citations_per_run` number, nullable
      - `brand_mention_runs` integer, required: Runs that mention the primary company.
      - `mention_rate` number, nullable: Share of runs that mention the primary company, from 0 to 1.
    - `change` PublicRateChanges, required
      - `owned_citations` number, nullable: Relative change from the previous period; 0.25 means 25% higher.
      - `owned_citations_per_run` number, nullable: Relative change from the previous period.
      - `mention_rate` number, nullable: Relative change from the previous period.

## Other responses

- `400`: The requested date range is invalid.
- `404`: No configured company was found for this organization.
- `422`: Validation Error

## Changes

> 8 revisions in range; 1 not diffed.

- **2026-10-28** `2c64a77a3936`: 3 info
  - added the optional property `coverage` to the response with the `200` status
  - added the optional property `period` to the response with the `200` status
  - added the optional property `rates` to the response with the `200` status

[Operation history](https://skmtc.dev/usesapient/apis/sapient-public-api/changes/v1/visibility/overview/get.md)

---

[API](https://skmtc.dev/usesapient/apis/sapient-public-api.md) - [All operations](https://skmtc.dev/usesapient/apis/sapient-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/usesapient/apis/sapient-public-api/revisions/14890dfe867e?raw)