AI Visibility

Get AI visibility check history

Get paginated history of AI visibility checks for a project. Each entry includes check timing and summary statistics with customer metrics, top competitor, and competitor rankings. The score counts only the top 5 positions in an answer, evenly spaced — first place the most, the last scoring position the least — and nothing below them. It is a reading of WHERE a brand lands when it is named, never of who is ahead: a standing claim — "you lead", "you trail", "the leader is X" — rests on how often each brand is named (presence on the market map, or mentionRate within one check) and never on this score, which can favour a brand named half as often. A score of 0 for a brand the answers did name means it was named only below the top 5, or too seldom inside them for the average to register. Read mentionRate beside a 0 score: a non-zero rate means the brand was named, and a 0 rate means no counted answer named it. Only scored checks are listed — under the full-coverage gate a cycle with a query it could not read is never scored and does not appear here; a query the model was read for and had no answer to show (noAnswerShown on that check's answers) does not count against it. Checks published before that gate remain listed and can have been scored over fewer answers than they asked queries; the queries-sent figure is not returned, so a listed check cannot be shown to be fully covered. Each entry carries summary.totalEntries, which is the size preview for that check's raw answers via the check-detail route. This page is subject to a response size cap: when truncated is true, whole entries were dropped from the end of items and pagination.hasMore does NOT account for them — lower limit to see the rest rather than paging forward, which would skip them.

get/v1/projects/{projectId}/ai-visibility/history

Request

Base URL: https://api.competlab.com
URL: https://api.competlab.com/v1/projects/{projectId}/ai-visibility/history
Auth: API key in header CL-API-Key

Path parameters

projectIdstring required

Example:507f1f77bcf86cd799439011

Project ID

Query parameters

pagenumber

Example:1

Page number (1-indexed)

limitnumber

Example:20

Number of items per page

view'compact' | 'full'

Example:compact

How much of the response to return. compact: each row's summary.competitorRankings carries its first 10 companies in stored order, then every tracked company and the customer's own row that fall outside them, with summary.competitorRankingsPage counting the whole list; summary.promptMarket.perPrompt is left out — the dashboard and a check's detail carry it. Every other field is unchanged. There is no offset: the whole list is view=full, or the check's detail. full: every row of every list, as stored — large, and meant for export rather than for reading. Omitted, the API's default view applies: compact on /v1.

Response

readingGuideobject

The rules for reading this response, keyed by the field they govern — a dotted path, where [] means any element of that array — and only for fields this response carries. First in either view. Read them before quoting a figure; they say what each field is and is not.

truncatedboolean required

True when the page exceeded the response size cap and whole entries were dropped from the end of items. pagination.total still reports the true number of checks, so a withheld entry is distinguishable from one that does not exist — but pagination.hasMore does NOT account for dropped rows, so paging forward on hasMore alone would skip them silently. Lower limit and re-request this page instead.

Example response

{
  "readingGuide": {
    "summary.pages": "Pages the engines RETRIEVED while answering, never pages they cited."
  },
  "items": [
    {
      "checkId": "507f1f77bcf86cd799439011",
      "completedAt": "2026-03-15T10:00:00.000Z",
      "summary": {
        "customer": {
          "domain": "mycompany.com",
          "mentionRate": 66.7,
          "mentionCount": 6,
          "aiScore": 73,
          "perProvider": {
            "openai": {
              "mentioned": true,
              "mentionCount": 3,
              "answersCounted": 3
            },
            "claude": {
              "mentioned": true,
              "mentionCount": 3,
              "answersCounted": 3
            },
            "gemini": {
              "mentioned": true,
              "mentionCount": 3,
              "answersCounted": 3
            },
            "perplexity": {
              "mentioned": true,
              "mentionCount": 3,
              "answersCounted": 3
            },
            "google_ai_overviews": {
              "mentioned": true,
              "mentionCount": 3,
              "answersCounted": 3
            }
          },
          "perPrompt": [
            {
              "promptLabel": "best sales forecasting platforms for mid-market teams",
              "mentionedBy": [
                "openai",
                "claude"
              ],
              "score": 61
            }
          ]
        },
        "topCompetitor": {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "mentionRate": 88.9
        },
        "mentionRateGap": -22.2,
        "totalCompetitorsFound": 8,
        "totalQueries": 12,
        "totalEntries": 45,
        "competitorRankings": [
          {
            "domain": "competitor.com",
            "name": "Competitor Inc",
            "mentionCount": 7,
            "mentionRate": 77.8,
            "aiScore": 68
          }
        ],
        "promptMarket": {
          "explanation": {
            "code": "rivals_found_across_answers",
            "text": "Your prompts are describing your market well. The AI answers we collected mention companies you already track, so the numbers here are measuring the right competition."
          },
          "answersNamingAnyRival": 34,
          "answersMatchingCurrentPromptText": 60,
          "checksAnalysed": 5,
          "perPrompt": [
            {
              "promptId": "7f3c1a2e-9d44-4c8b-9f0e-2b6a5c9d7e10",
              "promptTextInProject": "best sales forecasting platforms for mid-market teams",
              "explanation": {
                "code": "rivals_found_across_answers",
                "text": "Your prompts are describing your market well. The AI answers we collected mention companies you already track, so the numbers here are measuring the right competition."
              },
              "answersNamingAnyRival": 1,
              "answersMatchingCurrentPromptText": 20
            }
          ]
        },
        "competitorRankingsPage": {
          "limit": 10,
          "total": 96,
          "hasMore": true
        }
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.