--- title: "Retrieve Prompt Visibility Report" method: GET path: "/v1/visibility/prompts" tags: ["Visibility"] --- # Retrieve Prompt Visibility Report `GET /v1/visibility/prompts` ## Request - Base URL: `https://api.lightsage.com` - URL: `https://api.lightsage.com/v1/visibility/prompts` - Auth: API key in header `X-Lightsage-Api-Key` Returns the prompt visibility report for the organization. Returns an overall summary, topic rows, and nested active prompt rows. Each row includes recommendation score, recommendation score rank, visibility score, average position, owned-domain citations, and prompt runs for the selected date range. Active prompts without runs remain in the response with `null` visibility metrics and zero counts. ## Query parameters - `start_date` string, date - `end_date` string, date ## Response `200` Successful Response - PublicPromptVisibilityReportResponse - `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` PublicPromptVisibilityDateRange, required - `start_date` string, required - `end_date` string, required - `latest_run_date` string, nullable - `active_prompts_only` boolean - `has_data` boolean, required - `summary` PublicPromptVisibilitySummary, required - `prompt_count` integer, required - `topic_count` integer, required - `metrics` PublicPromptVisibilityMetrics, 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. - `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`. - `average_position` number, nullable: Mean mention position in AI responses; 1 is first and lower is better. 0 when runs produced no mentions. - `citation_count` integer: Owned-domain citations only. - `run_count` integer: One per prompt, platform, and run date. - `topics` PublicTopicVisibilityRow[] - `id` string, required - `name` string, required - `prompt_count` integer, required - `metrics` PublicPromptVisibilityMetrics, 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. - `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`. - `average_position` number, nullable: Mean mention position in AI responses; 1 is first and lower is better. 0 when runs produced no mentions. - `citation_count` integer: Owned-domain citations only. - `run_count` integer: One per prompt, platform, and run date. - `prompts` PublicPromptVisibilityRow[] - `id` string, required - `text` string, required - `metrics` PublicPromptVisibilityMetrics, 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. - `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`. - `average_position` number, nullable: Mean mention position in AI responses; 1 is first and lower is better. 0 when runs produced no mentions. - `citation_count` integer: Owned-domain citations only. - `run_count` integer: One per prompt, platform, and run date. - `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/prompts/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)