> ## Documentation Index
> Fetch the complete documentation index at: https://lightsage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Prompt Visibility Report

> Retrieve the prompt visibility report for the organization.

Mirrors the dashboard Prompts tab with an overall summary, topic rows, and
nested active prompt rows. Each row includes visibility score, visibility
rank, share of voice, 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.



## OpenAPI

````yaml /openapi.json get /v1/visibility/prompts
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: []
paths:
  /v1/visibility/prompts:
    get:
      tags:
        - Visibility
      summary: Retrieve Prompt Visibility Report
      description: >-
        Retrieve the prompt visibility report for the organization.


        Mirrors the dashboard Prompts tab with an overall summary, topic rows,
        and

        nested active prompt rows. Each row includes visibility score,
        visibility

        rank, share of voice, 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.
      operationId: visibility_prompts_retrieve
      parameters:
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
            description: Optional start date. Defaults to 30 days before the end date.
            title: Start Date
          description: Optional start date. Defaults to 30 days before the end date.
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
            description: Optional end date. Defaults to today.
            title: End Date
          description: Optional end date. Defaults to today.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicPromptVisibilityReportResponse'
        '400':
          description: The requested date range is invalid.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                  - detail
              examples:
                invalid_date_range:
                  summary: Invalid date range
                  value:
                    detail: start_date must be on or before end_date
        '404':
          description: No configured company was found for this organization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
                required:
                  - detail
              examples:
                missing_company:
                  summary: Missing company
                  value:
                    detail: >-
                      Configured API Performance scope not found for this
                      organization
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - LightsageApiKeyAuth: []
components:
  schemas:
    PublicPromptVisibilityReportResponse:
      properties:
        company:
          $ref: '#/components/schemas/PublicCompany'
        date_range:
          $ref: '#/components/schemas/PublicPromptVisibilityDateRange'
        has_data:
          type: boolean
          title: Has Data
          description: Whether the selected date range contains prompt-run data.
        summary:
          $ref: '#/components/schemas/PublicPromptVisibilitySummary'
        topics:
          items:
            $ref: '#/components/schemas/PublicTopicVisibilityRow'
          type: array
          title: Topics
          description: Topic and prompt rows shown in the prompt visibility report.
      type: object
      required:
        - company
        - date_range
        - has_data
        - summary
      title: PublicPromptVisibilityReportResponse
    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
      type: object
      required:
        - name
      title: PublicCompany
    PublicPromptVisibilityDateRange:
      properties:
        start_date:
          type: string
          title: Start Date
          description: Start date used for the calculation.
        end_date:
          type: string
          title: End Date
          description: End date used for the calculation.
        latest_run_date:
          anyOf:
            - type: string
            - type: 'null'
          title: Latest Run Date
          description: Latest prompt-run date included in the calculation.
        active_prompts_only:
          type: boolean
          title: Active Prompts Only
          description: Whether only currently active prompts were included.
          default: true
      type: object
      required:
        - start_date
        - end_date
      title: PublicPromptVisibilityDateRange
    PublicPromptVisibilitySummary:
      properties:
        prompt_count:
          type: integer
          title: Prompt Count
          description: Active prompts included in the report.
        topic_count:
          type: integer
          title: Topic Count
          description: Topics containing active prompts.
        metrics:
          $ref: '#/components/schemas/PublicPromptVisibilityMetrics'
      type: object
      required:
        - prompt_count
        - topic_count
        - metrics
      title: PublicPromptVisibilitySummary
    PublicTopicVisibilityRow:
      properties:
        id:
          type: string
          title: Id
          description: Stable prompt topic identifier.
        name:
          type: string
          title: Name
          description: Prompt topic name.
        prompt_count:
          type: integer
          title: Prompt Count
          description: Active prompts in this topic.
        metrics:
          $ref: '#/components/schemas/PublicPromptVisibilityMetrics'
        prompts:
          items:
            $ref: '#/components/schemas/PublicPromptVisibilityRow'
          type: array
          title: Prompts
          description: Active prompts in the topic with date-range metrics.
      type: object
      required:
        - id
        - name
        - prompt_count
        - metrics
      title: PublicTopicVisibilityRow
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    PublicPromptVisibilityMetrics:
      properties:
        visibility_score:
          anyOf:
            - type: number
            - type: 'null'
          title: Visibility Score
          description: Visibility score aggregated over the date range, from 0 to 1.
        visibility_score_rank:
          anyOf:
            - type: integer
            - type: 'null'
          title: Visibility Score Rank
          description: Rank by visibility score among tracked companies.
        share_of_voice:
          anyOf:
            - type: number
            - type: 'null'
          title: Share Of Voice
          description: Share of voice aggregated over the date range, from 0 to 1.
        average_position:
          anyOf:
            - type: number
            - type: 'null'
          title: Average Position
          description: Average mention position aggregated over the date range.
        citation_count:
          type: integer
          title: Citation Count
          description: Owned-domain citations found in prompt runs for the date range.
          default: 0
        run_count:
          type: integer
          title: Run Count
          description: Prompt runs included in the date-range calculation.
          default: 0
      type: object
      title: PublicPromptVisibilityMetrics
    PublicPromptVisibilityRow:
      properties:
        id:
          type: string
          title: Id
          description: Stable prompt identifier.
        text:
          type: string
          title: Text
          description: Prompt text.
        metrics:
          $ref: '#/components/schemas/PublicPromptVisibilityMetrics'
      type: object
      required:
        - id
        - text
        - metrics
      title: PublicPromptVisibilityRow
  securitySchemes:
    LightsageApiKeyAuth:
      type: apiKey
      in: header
      name: X-Lightsage-Api-Key

````