retrieve current visibility.md
Retrieve Current Visibility
Returns recommendation score, visibility score, ranks, and date-range metadata for the configured primary company. Metrics are computed from active prompts only; when no data exists, values are null.
OpenAPI
openapi: 3.1.0
info:
title: Lightsage Public API
description: Public API for Lightsage CLI and external integrations.
version: 1.0.0
servers:
- url: https://api.lightsage.com
description: Production
security: []
tags:
- name: Status
description: Check API availability and validate the calling API key.
- name: Visibility
description: >-
Measure visibility, citations, competitors, and prompt performance across
answer platforms.
- name: Prompts
description: Manage tracked prompts and topics, and inspect their stored runs.
- name: Opportunities
description: Review ranked opportunities computed from prompt visibility results.
- name: Tasks
description: Manage the persisted action queue and task lifecycle.
- name: Site Audits
description: Review website audit results and page-level findings.
- name: Agent Analytics
description: >-
See which coding agents, AI bots, and people visit your tracked sites,
which pages they read, which pages return errors, and where the visits
come from.
- name: Evals
description: Define eval tasks, judges, subjects, and saved configurations.
- name: Eval Templates
description: >-
Select reusable judges, targets, schedules, metadata, and runtime settings
with `POST /v2/eval-templates`, then copy only those settings into
prompt-specific evals with `POST /v2/evals/batch`. Templates never contain
prompts and remain independent from evals created from them.
- name: Eval Runs
description: Start eval runs and inspect their lifecycle state.
- name: Eval Results
description: Review completed eval outcomes and diagnostic details.
- name: Agent Preference
description: >-
Compare your company head-to-head with a tracked competitor. Create a
comparison with `POST /v2/agent-preference/evals`, run it with `POST
/v2/eval-runs`, then read which company agents recommended.
- name: Agents
description: List runnable coding-agent harness and model combinations.
- name: Repositories
description: Manage reusable Git repository workspaces.
- name: Environments
description: List reusable runtime environments without exposing secret values.
- name: MCP Servers
description: List reusable MCP server integrations without exposing credentials.
- name: CLIs
description: List reusable command-line interfaces without exposing setup commands.
- name: Skills
description: List reusable skills available to workflows and evals.
paths:
/v2/visibility/current:
get:
tags:
- Visibility
summary: Retrieve Current Visibility
description: >-
Returns recommendation score, visibility score, ranks, and date-range
metadata for the configured primary company. Metrics are computed from
active prompts only; when no data exists, values are `null`.
operationId: v2_visibility_current_retrieve
parameters:
- name: start_date
in: query
required: false
schema:
type: string
format: date
title: Start Date
description: >-
Inclusive range start; defaults to 30 days before the end date. The
range may span at most 90 days.
- name: end_date
in: query
required: false
schema:
type: string
format: date
title: End Date
description: Inclusive range end; defaults to today.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PublicCurrentVisibilityResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- LightsageApiKeyAuth: []
components:
schemas:
PublicCurrentVisibilityResponse:
properties:
company:
$ref: '#/components/schemas/PublicCompany'
recommendation_score:
anyOf:
- type: number
- type: 'null'
title: Recommendation Score
description: >-
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:
anyOf:
- type: integer
- type: 'null'
title: Recommendation Score Rank
visibility_score:
anyOf:
- type: number
- type: 'null'
title: Visibility Score
description: >-
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:
anyOf:
- type: integer
- type: 'null'
title: Visibility Score Rank
share_of_voice:
anyOf:
- type: number
- type: 'null'
title: Share Of Voice
description: >-
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:
anyOf:
- type: integer
- type: 'null'
title: Share Of Voice Rank
description: Rank by `share_of_voice` among tracked companies, highest first.
average_position:
anyOf:
- type: number
- type: 'null'
title: Average Position
description: >-
Mean mention position in AI responses; 1 is first and lower is
better.
average_position_rank:
anyOf:
- type: integer
- type: 'null'
title: Average Position Rank
date:
anyOf:
- type: string
- type: 'null'
title: Date
description: Latest prompt-run date in the range.
start_date:
type: string
title: Start Date
end_date:
type: string
title: End Date
active_prompts_only:
type: boolean
title: Active Prompts Only
default: true
has_data:
type: boolean
title: Has Data
type: object
required:
- company
- start_date
- end_date
- has_data
title: PublicCurrentVisibilityResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PublicCompany:
properties:
name:
type: string
title: Name
domain:
anyOf:
- type: string
- type: 'null'
title: Domain
logo_url:
anyOf:
- type: string
- type: 'null'
title: Logo Url
relationship:
anyOf:
- type: string
- type: 'null'
title: Relationship
description: >-
The company relationship: `primary` for the organization's own
company or `competitor` for a tracked competitor.
type: object
required:
- name
title: PublicCompany
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
securitySchemes:
LightsageApiKeyAuth:
type: apiKey
in: header
name: X-Lightsage-Api-Key