> ## 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 Citation Summary > Returns citation totals grouped by URL prefix (domain and first path segment, such as `example.com/blog`), URL, domain, or day, each compared with the previous period, with per-run rates and run coverage. Filter to one section of a site with `url_prefix`, for example `https://example.com/blog/`. Aggregated in one call; use it instead of paging the citations list. ## OpenAPI ````yaml /openapi.json get /v2/visibility/citations/summary 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/citations/summary: get: tags: - Visibility summary: Retrieve Citation Summary description: >- Returns citation totals grouped by URL prefix (domain and first path segment, such as `example.com/blog`), URL, domain, or day, each compared with the previous period, with per-run rates and run coverage. Filter to one section of a site with `url_prefix`, for example `https://example.com/blog/`. Aggregated in one call; use it instead of paging the citations list. operationId: v2_visibility_citations_summary_retrieve parameters: - name: period in: query required: false schema: type: string maxLength: 20 title: Period description: >- Named period, resolved in UTC by the server: `last_7_days`, `last_14_days`, `last_30_days`, `last_90_days` (N days ending today), `this_week`, `last_week`, an ISO week such as `2026-W43` (Monday to Sunday), `this_month`, `last_month`, a month such as `2026-10`, `this_quarter`, `last_quarter`, or a quarter such as `2026Q4`. A current week, month, or quarter ends today. The response's `period` gives the resolved dates and the matching previous period. Do not combine with `start_date` or `end_date`. - 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. - name: group_by in: query required: false schema: enum: - url_prefix - url - domain - day type: string default: url_prefix title: Group By description: How to group citations. - name: url_prefix in: query required: false schema: type: string maxLength: 500 title: Url Prefix description: >- Only citations under this URL prefix, such as `https://example.com/blog/`. Scheme and `www.` are ignored. - name: source_type in: query required: false schema: enum: - all - owned - external type: string default: all title: Source Type description: All citations, only owned company domains, or only external ones. - name: platform in: query required: false schema: type: string title: Platform description: Optional answer-platform ID, name, or slug. - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit description: Groups to return; `day` groups return every day. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PublicCitationSummaryResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - LightsageApiKeyAuth: [] components: schemas: PublicCitationSummaryResponse: properties: period: $ref: '#/components/schemas/PublicResolvedPeriod' description: The resolved period and the previous period it is compared with. group_by: type: string enum: - url_prefix - url - domain - day title: Group By url_prefix: anyOf: - type: string - type: 'null' title: Url Prefix description: URL prefix filter applied, if any. source_type: type: string enum: - all - owned - external title: Source Type platform: anyOf: - type: string - type: 'null' title: Platform headline_metric: type: string enum: - citation_count - citations_per_run title: Headline Metric description: >- The number to lead with: citation counts when the periods are comparable, otherwise citations per run. totals: $ref: '#/components/schemas/PublicCitationSummaryTotals' has_data: type: boolean title: Has Data group_count: type: integer title: Group Count description: Groups matching the filters, before `limit`. count: type: integer title: Count description: Groups returned. groups: items: $ref: '#/components/schemas/PublicCitationSummaryGroup' type: array title: Groups description: >- Groups by citation count, most first; `day` groups are in date order. coverage: $ref: '#/components/schemas/PublicCoverage' description: >- Runs per day against expected runs for both periods. Check `comparable` before comparing totals. type: object required: - period - group_by - source_type - headline_metric - totals - has_data - group_count - count - coverage title: PublicCitationSummaryResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError PublicResolvedPeriod: properties: name: anyOf: - type: string - type: 'null' title: Name description: >- The `period` requested, or null when the range came from `start_date` and `end_date`. start_date: type: string title: Start Date description: First day of the period (UTC), inclusive. end_date: type: string title: End Date description: Last day of the period (UTC), inclusive. days: type: integer title: Days description: Days in the period, counting both ends. previous_start_date: type: string title: Previous Start Date description: First day of the previous period it is compared with. previous_end_date: type: string title: Previous End Date description: >- 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: type: integer title: Previous Days description: Days in the previous period. partial: type: boolean title: Partial description: >- Whether the period includes today, so its last day is still in progress. timezone: type: string const: UTC title: Timezone default: UTC type: object required: - start_date - end_date - days - previous_start_date - previous_end_date - previous_days - partial title: PublicResolvedPeriod PublicCitationSummaryTotals: properties: citation_count: type: integer title: Citation Count previous_citation_count: type: integer title: Previous Citation Count change: anyOf: - type: number - type: 'null' title: Change description: Relative change in citations; 0.25 means 25% higher. run_count: type: integer title: Run Count description: >- Successful runs of active prompts in the period, after the platform filter. previous_run_count: type: integer title: Previous Run Count citations_per_run: anyOf: - type: number - type: 'null' title: Citations Per Run previous_citations_per_run: anyOf: - type: number - type: 'null' title: Previous Citations Per Run per_run_change: anyOf: - type: number - type: 'null' title: Per Run Change description: Relative change in citations per run. url_count: type: integer title: Url Count description: Distinct cited URLs in the period. type: object required: - citation_count - previous_citation_count - run_count - previous_run_count - url_count title: PublicCitationSummaryTotals PublicCitationSummaryGroup: properties: key: type: string title: Key description: >- The group: a URL prefix (domain and first path segment, such as `example.com/blog`), a normalized URL, a domain, or a day (YYYY-MM-DD). url: anyOf: - type: string - type: 'null' title: Url description: Most frequently observed variant of the URL, for `url` groups. title: anyOf: - type: string - type: 'null' title: Title description: Page title, for `url` groups. is_company_link: type: boolean title: Is Company Link description: Whether the group includes an owned company domain. citation_count: type: integer title: Citation Count description: Citations in the period. previous_citation_count: type: integer title: Previous Citation Count description: >- Citations in the previous period. For `day` groups, the matching day of the previous period. change: anyOf: - type: number - type: 'null' title: Change description: Relative change in citations; 0.25 means 25% higher. citations_per_run: anyOf: - type: number - type: 'null' title: Citations Per Run previous_citations_per_run: anyOf: - type: number - type: 'null' title: Previous Citations Per Run per_run_change: anyOf: - type: number - type: 'null' title: Per Run Change description: Relative change in citations per run. prompt_count: type: integer title: Prompt Count description: Distinct active prompts that cited the group in the period. url_count: type: integer title: Url Count description: Distinct URLs in the group in the period. type: object required: - key - is_company_link - citation_count - previous_citation_count - prompt_count - url_count title: PublicCitationSummaryGroup PublicCoverage: properties: comparable: type: boolean title: Comparable description: >- 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: items: type: string type: array title: Notes description: Why the periods are not comparable, in plain sentences. current: $ref: '#/components/schemas/PublicPeriodCoverage' previous: $ref: '#/components/schemas/PublicPeriodCoverage' days: items: $ref: '#/components/schemas/PublicCoverageDay' type: array title: Days type: object required: - comparable - current - previous title: PublicCoverage 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 PublicPeriodCoverage: properties: start_date: type: string title: Start Date end_date: type: string title: End Date runs: type: integer title: Runs expected_runs: type: integer title: Expected Runs complete_days: type: integer title: Complete Days description: Days in the period other than today in progress. runs_per_day: anyOf: - type: number - type: 'null' title: Runs Per Day description: Runs per complete day. missing_days: items: type: string type: array title: Missing Days short_days: items: type: string type: array title: Short Days type: object required: - start_date - end_date - runs - expected_runs - complete_days title: PublicPeriodCoverage PublicCoverageDay: properties: date: type: string title: Date period: type: string enum: - current - previous title: Period runs: type: integer title: Runs description: Successful prompt runs of active prompts that day. expected_runs: type: integer title: Expected Runs description: >- Median daily runs over the 7 days before; 0 when no daily runs are expected. status: type: string enum: - ok - short - missing - in_progress - not_expected title: Status description: >- `missing`: no runs on a day that expected some. `short`: under half the expected runs. `in_progress`: today, before its runs finished. type: object required: - date - period - runs - expected_runs - status title: PublicCoverageDay securitySchemes: LightsageApiKeyAuth: type: apiKey in: header name: X-Lightsage-Api-Key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.