> ## Documentation Index > Fetch the complete documentation index at: https://rankspot.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get AI visibility summary > How your brand did in AI answers over a period: four headline scores, the split across platforms, and the ten most-mentioned brands with yours among them. **Requires:** `startDate` and `endDate`. Unlike the list endpoints, a summary reports on a bounded period. **Comparing periods:** call it twice with two equal-length periods and compare the scores. Equal length matters — a 30-day period against a 7-day one measures the calendar, not your visibility. **Reading a null:** every score is nullable and null means the period had no data to compute it from, which is not the same as zero. A workspace whose runs all failed scores null, not 0%. Check `responsesCounted` before quoting any of them. **What counts:** runs that failed or never completed are excluded throughout, so a provider outage does not read as a period of poor visibility. **Your own row:** `shareOfVoice` and `categoryRank` are your entry in `leaderboard`, lifted out. Your brand always appears there, even at zero mentions or outside the top ten. ## OpenAPI ````yaml https://api.rankspot.ai/docs-json get /v1/ai-visibility/summary openapi: 3.0.0 info: title: RankSpot Public API description: >- The RankSpot Public API gives you programmatic access to your workspace data — keywords, backlinks, competitors, planned actions, articles, and more. ## Authentication All endpoints require a Bearer API key in the `Authorization` header: ``` Authorization: Bearer ``` Generate API keys from **Settings → API Keys** in the RankSpot dashboard. Each key is scoped to a single workspace. ## Pagination List endpoints return a consistent envelope: ```json { "data": { "total": 120, "offset": 0, "limit": 20, "count": 20, "items": [...] } } ``` Use `offset` and `limit` query parameters to paginate. Default limit is **20**, maximum is **100**. ## Status codes | Code | Meaning | |------|---------| | 200 | Success | | 201 | Created | | 204 | No content (delete / unarchive) | | 400 | Validation error or business rule violation | | 401 | Missing or invalid API key | | 404 | Resource not found or belongs to another workspace | version: '1.0' contact: {} servers: - url: https://api.rankspot.ai description: Production security: [] tags: - name: AI Visibility description: >- How AI answer engines see your brand. Track prompts, read the answers ChatGPT, Perplexity and Google gave, and work through the pages they cited. Prompts are run on a daily schedule by RankSpot, so answers appear after the next run rather than on demand. - name: Articles description: >- AI-generated blog articles. Articles are created automatically when a `write_article` action is sent to generation — they cannot be created directly via the API. - name: Backlinks description: >- Backlinks discovered for your domain and your competitors' domains. Backlinks are auto-synced on a background interval and cannot be created via the API. - name: Categories description: Categories for organising actions and articles within your workspace. - name: Competitors description: >- Competitor domains tracked in your workspace. Once added, keywords and backlinks for each competitor are fetched asynchronously on a background sync interval. - name: Forum Opportunities description: >- Forum threads and community posts surfaced as potential link-building or engagement opportunities. - name: Keywords description: >- SEO keywords tracked in your workspace, enriched with search volume, competition, and AI-generated relevance scores. - name: People Also Ask description: >- "People also ask" questions discovered from search results for your tracked keywords. - name: Actions description: >- The SEO work planned for your workspace. Each action carries a `type` saying what kind of work it is and which target it points at — see `POST /v1/actions` for the full list. Only `write_article` can be turned into an article; the rest are a person's job. Create actions yourself or let RankSpot generate them. - name: Research description: >- Live lookups against the open web: a Google search and a page fetch. The only endpoints here that spend credits per call. Neither response reports what it cost — the charge is real, and your remaining balance is visible in the RankSpot dashboard. Returns 402 when the workspace is out of credits. - name: Search Console description: >- Google Search Console performance data — clicks, impressions, CTR, and average position for your connected property. Requires GSC to be connected from the RankSpot dashboard. - name: Workspace description: >- Who the workspace is: brand, domain, what the business does and who it sells to. Read this first — the rest of the API returns opportunities that only mean something in the context of a particular business. paths: /v1/ai-visibility/summary: get: tags: - AI Visibility summary: Get AI visibility summary description: >- How your brand did in AI answers over a period: four headline scores, the split across platforms, and the ten most-mentioned brands with yours among them. **Requires:** `startDate` and `endDate`. Unlike the list endpoints, a summary reports on a bounded period. **Comparing periods:** call it twice with two equal-length periods and compare the scores. Equal length matters — a 30-day period against a 7-day one measures the calendar, not your visibility. **Reading a null:** every score is nullable and null means the period had no data to compute it from, which is not the same as zero. A workspace whose runs all failed scores null, not 0%. Check `responsesCounted` before quoting any of them. **What counts:** runs that failed or never completed are excluded throughout, so a provider outage does not read as a period of poor visibility. **Your own row:** `shareOfVoice` and `categoryRank` are your entry in `leaderboard`, lifted out. Your brand always appears there, even at zero mentions or outside the top ten. operationId: AiSummaryController_get parameters: - name: startDate required: true in: query description: Inclusive start of the period, `YYYY-MM-DD` (UTC). schema: type: string example: '2026-07-01' - name: endDate required: true in: query description: Inclusive end of the period, `YYYY-MM-DD` (UTC). schema: type: string example: '2026-07-28' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/AiSummaryDto' '400': description: >- Missing or malformed dates, or `invalid-date-range` when `startDate` is later than `endDate`. security: - bearer: [] components: schemas: AiSummaryDto: type: object properties: startDate: type: string example: '2026-07-01' endDate: type: string example: '2026-07-28' visibilityScore: type: number example: 42.9 nullable: true description: >- Share of answers that named your brand, 0-100, as an unweighted mean of the per-platform scores. null when nothing ran in the period, which is not the same as 0. shareOfVoice: type: number example: 22.5 nullable: true description: >- Your mentions as a share of all brand mentions, 0-100. Your own row in `leaderboard`, lifted out. null when no brand was mentioned at all. citationShare: type: number example: 8.1 nullable: true description: >- Citations pointing at your own domain as a share of all citations, 0-100. categoryRank: type: number example: 3 nullable: true description: >- Your 1-based position in `leaderboard`. null when the workspace has no own brand set. responsesCounted: type: number example: 112 description: >- Answers the scores are computed from. Read it before quoting the others: 100% visibility across two answers is not the same claim as 100% across two hundred. platforms: type: object additionalProperties: type: number nullable: true example: chatgpt: 66.7 perplexity: 25 google_ai_overview: null google_ai_mode: 0 description: >- Visibility per platform, 0-100. null means the platform produced no answer in the period; 0 means it answered and never named you. `visibilityScore` is the unweighted mean of the non-null entries. leaderboard: description: >- The ten most-mentioned brands, most first, with your own always included even when it falls outside the ten or was never mentioned. Brands hidden in the dashboard are excluded, including from the share-of-voice denominator. type: array items: $ref: '#/components/schemas/LeaderboardEntryDto' required: - startDate - endDate - visibilityScore - shareOfVoice - citationShare - categoryRank - responsesCounted - platforms - leaderboard LeaderboardEntryDto: type: object properties: competitorId: type: string example: 3f1c2b4e-8d5a-4a2f-9c3e-7b1d6a5e4c20 name: type: string example: RankSpot domain: type: string example: rankspot.ai isOwnBrand: type: boolean example: true mentions: type: number example: 31 description: Times the answers named this brand. shareOfVoice: type: number example: 27.7 description: >- This brand as a share of all mentions in the period, 0-100. Measured against every brand named, not only the ten returned, so the rows here need not sum to 100. position: type: number example: 1 description: 1-based, most mentioned first. sentiment: type: number example: 82 nullable: true description: >- Mean of how favourably the answers spoke of this brand, 0-100. null when no answer carried a sentiment for it. required: - competitorId - name - domain - isOwnBrand - mentions - shareOfVoice - position - sentiment securitySchemes: bearer: scheme: bearer bearerFormat: JWT type: http ````