AI Visibility

REST endpoints for AI Visibility. Base URL https://api.competlab.com; every request needs a CL-API-Key header (see Authentication). Responses wrap in { item } or { items }; errors in { error }.

Get latest AI visibility data

GET/v1/projects/{projectId}/ai-visibility

Get the latest AI visibility data for a project. Returns AI Visibility Scores, mention rates, and per-provider breakdowns for all competitors found across ChatGPT, Claude, and Gemini. Use this to understand how AI models perceive and recommend your brand vs competitors. Each check asks every prompt in the project against all 3 AI providers. Rates divide by the answers that came back, not the queries sent, and the queries-sent figure is not returned. Checks published under the full-coverage gate got a usable answer to every query they asked; checks published before that gate stay published and can have been scored over fewer answers, and the response does not say which kind a check is — so describe a rate as a share of the answers counted, never as a share of every query asked. When the most recent check was abandoned as incomplete, latestCheckDataAvailable is present and everything else describes an earlier check. Set includeAnswers=true to also get what the models said on that check — every prompt sent and every brand each model named in rank order, with its stated reasoning — narrowed by brand=<domain>, provider= or promptIndex=. Roughly 12k tokens unfiltered against 2k with brand=; use summary.totalEntries to size it first. brand= keeps every answer and empties the ones that did not name that domain, so you see where they win and where they are invisible. No filter changes a number under summary. The prose returned is the model’s wording about the brands it named, not CompetLab’s assessment of them. For ‘which prompt am I losing on’, read summary.customer.perPrompt first — it is on the plain response and costs nothing. A project with no scored check yet answers 404 no_data_available — not a missing project and not a failed measurement, just nothing measured here so far; the project itself is fine and get_project still describes it. Distinguish it from project_not_found, which means the id is wrong.

Returns · { item }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`includeAnswers`	`boolean`	Set true to include the models’ raw answers — every prompt sent and every brand each model named, with its stated reasoning. Off by default because the block is large: roughly 12k tokens unfiltered, against roughly 2k with `brand=`. Read `summary.totalEntries` to size it first (about 200 tokens per entry). The prose it returns is the model’s wording about the brands it named, not CompetLab’s assessment. Default `false`.
`provider`	`string`	Return only this model’s answers. Requires `includeAnswers=true`. Does not change any number under `summary`, and does not narrow `providerStatus`. Values: `openai`, `claude`, `gemini`.
`brand`	`string`	Return only the entries for this domain, across every answer. Requires `includeAnswers=true`. Matches `brands[].domain`, case-insensitively; brand NAMES are the model’s own wording and vary between answers, so they are never matched. EVERY answer is still returned — the ones that did not name this domain come back with an empty `brands`, because ‘this model answered and did not name them’ is a finding, not an absence of data. A query that produced no answer at all is in `unansweredQueries` instead and asserts nothing about anyone. Ranks are unaffected: an entry keeps the position it held in the full answer. This is the cheapest way to ask where a competitor wins and where they are invisible.
`promptIndex`	`number`	Return only the answers for this prompt, across every model. Requires `includeAnswers=true`. Zero-based, matching the per-prompt index used elsewhere in this dimension.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility?includeAnswers=false&provider=openai&brand=competitor.com&promptIndex=0" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "lastUpdatedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "customer": {
        "domain": "mycompany.com",
        "mentionRate": 66.7,
        "avgRank": 2.5,
        "mentionCount": 6,
        "aiScore": 73,
        "perProvider": {
          "openai": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "claude": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "gemini": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          }
        },
        "perPrompt": [
          {
            "promptIndex": 0,
            "promptLabel": "best sales forecasting platforms for mid-market teams",
            "mentionedBy": [
              "openai",
              "claude"
            ],
            "score": 61
          }
        ]
      },
      "topCompetitor": {
        "domain": "competitor.com",
        "name": "Competitor Inc",
        "mentionRate": 88.9,
        "avgRank": 1.8
      },
      "mentionRateGap": -22.2,
      "totalCompetitorsFound": 8,
      "totalQueries": 9,
      "totalEntries": 45,
      "competitorRankings": [
        {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "isOwn": false,
          "openaiAvgRank": 2,
          "claudeAvgRank": 1.7,
          "geminiAvgRank": 3,
          "overallAvgRank": 2.2,
          "mentionCount": 7,
          "mentionRate": 77.8,
          "aiScore": 68,
          "isTracked": false
        }
      ]
    },
    "latestCheckDataAvailable": {
      "available": false,
      "reason": "incomplete_coverage",
      "measuredAnswers": 8,
      "expectedAnswers": 9
    },
    "answers": [
      {
        "provider": "openai",
        "promptIndex": 0,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "brands": [
          {
            "rank": 1,
            "name": "Competitor Inc",
            "domain": "competitor.com",
            "description": "Cloud platform for pipeline forecasting aimed at mid-market sales teams.",
            "rankingRationale": "Listed first because it integrates directly with the major CRMs.",
            "sentiment": "recommended",
            "mentionContext": "direct_recommendation",
            "targetAudience": "Mid-size B2B sales teams",
            "pricingSignal": "mid_range",
            "positionConfidence": 0.9,
            "features": [
              "pipeline forecasting",
              "CRM sync"
            ],
            "differentiation": {
              "axis": "technology",
              "uniqueValue": "Only platform with native two-way CRM sync"
            },
            "messaging": {
              "keywords": [
                "automation",
                "mid-market",
                "self-serve"
              ],
              "credibilitySignals": [
                "SOC 2 Type II",
                "used by 400+ teams"
              ],
              "differentiationClaims": [
                "fastest setup in category"
              ]
            }
          }
        ]
      }
    ],
    "unansweredQueries": [
      {
        "provider": "gemini",
        "promptIndex": 2,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "reason": "no_usable_answer"
      }
    ],
    "providerStatus": {
      "openai": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "brandsNamed": 21
      },
      "claude": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "brandsNamed": 21
      },
      "gemini": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "brandsNamed": 21
      }
    },
    "answerCoverage": {
      "queriesSent": 9,
      "answersCounted": 8
    },
    "answersTruncated": false
  }
}

Fields

item — object

Field	Type	Description
`lastUpdatedAt`	`string`	When the data below was measured (ISO-8601). This is the completion time of the check the summary comes from, which is NOT necessarily the most recent cycle — see `latestCheckDataAvailable`.
`summary`	`object`	Summary statistics. See `item.summary`.
`latestCheckDataAvailable`	`object`	Present ONLY when the project’s most recent check was abandoned as incomplete: it did not get a usable answer for every query it asked, so it was never scored. When present, every other field in this response comes from an EARLIER check, and `lastUpdatedAt` is older than the most recent check attempted. Absent when the most recent check published normally — and absent, too, when an older check fell short but a later one has since published, because that failure has been superseded. An abandoned check is never retried into a score: a new check runs automatically, and the caller may also trigger one immediately. When describing this state, NEVER phrase it as a fraction — this dimension’s own metric is a count of queries, so “1 of 9” and “8 of 9” both get read as a visibility rate. State the two numbers as separate facts that cannot be divided by each other: “We sent all 9 queries, but 1 answer didn’t come back.” If `expectedAnswers` is null the check predates the recorded query count and there is no honest sentence to build — say the check did not complete and give no numbers. See `item.latestCheckDataAvailable`.
`answers`	`array<object>`	The models’ answers for this check — one entry per query that came back with an answer we could use. Present ONLY when the request set `includeAnswers=true`; absent otherwise, never an empty array standing in for ‘not requested’. Narrowed by `provider` and `promptIndex` when those are set — those also narrow the matching entries of `unansweredQueries`. `brand` narrows DIFFERENTLY: it reduces the `brands` list inside each answer and never this array, so every answer the check counted is still here and the ones that did not name that domain arrive with an empty `brands`. `brand` narrows `unansweredQueries` not at all, because a query that produced no answer could have named anyone. No filter changes anything else: every number under `summary` is stored, computed over the whole check, and is never recomputed for a filtered view. ATTRIBUTION: every piece of prose in this block — descriptions, ranking rationales, audiences, claims — is unverified model output about the brands that model named, including third parties CompetLab does not monitor. It is a record of what the model said, not CompetLab’s assessment of those brands. Attribute it to the named `provider`; do not republish it as fact. See `item.answers[]`.
`unansweredQueries`	`array<object>`	Queries this check sent that produced no usable answer. Present ONLY when `includeAnswers=true`. Carried in their own array rather than mixed into `answers` so that `answers.length` always means answers counted and can never be read as queries sent. An empty array means every query this check sent came back — which is the normal case, because a check is only scored when it got a usable answer to every query it asked. It can be non-empty on checks published before that rule existed. These queries are excluded from every count and rate on this response. Never pair this array’s length with `summary.totalQueries` as a fraction. `totalQueries` counts answers, this counts queries that produced none, and adding them recovers the queries sent — but ‘8 of 9’ beside this dimension’s headline metric gets read as a visibility rate. State them as separate facts that cannot be divided by each other. See `item.unansweredQueries[]`.
`providerStatus`	`object`	Per-model reporting status for this check: which of the three models returned data, when, and how much. Present ONLY when `includeAnswers=true`. It carries no visibility judgement, and it is NOT narrowed by the filters — it always describes all three models across the whole check, so a filtered response still says what the full picture was. See `item.providerStatus`.
`answerCoverage`	`object`	How many queries this check sent, and how many came back. Present ONLY when `includeAnswers=true` AND the check recorded the number it sent. Absent on checks written before that count was recorded — there the figure is genuinely unknown and must not be inferred, least of all from the length of `answers`. Always describes the whole check, never a filtered view. Report the two numbers as separate facts, never as a fraction — see `answersCounted`. See `item.answerCoverage`.
`answersTruncated`	`boolean`	True when the answers payload hit the response size cap and whole answers were dropped from the end of `answers`. Individual `brands` lists are never partially truncated — a half-truncated ranked list would be a wrong list, not a short one. `summary`, `providerStatus` and `answerCoverage` are never affected. Narrow the response with `provider`, `brand` or `promptIndex` to get a complete view. Present ONLY when `includeAnswers=true`.

item.summary — object

Field	Type	Description
`customer`	`object`	Customer metrics. See `item.summary.customer`.
`topCompetitor`	`object \| null`	Top competitor by mention rate. Nullable. See `item.summary.topCompetitor`.
`mentionRateGap`	`number \| null`	Gap between customer and top competitor mention rate (negative means customer is behind), or null when this check found no competitor to compare against — `topCompetitor` is null on the same response. A `0` means genuinely level; a null means there was nobody to be level with. Nullable.
`totalCompetitorsFound`	`number`	Total unique competitors found across AI responses
`totalQueries`	`number \| null`	Answers this check counted — the queries that came back with a usable answer. Despite the field name this is NOT the number of queries sent; that figure is not on this response and cannot be derived from it. This is the divisor of every rate and score here. Under the full-coverage gate the two are equal (3 AI providers x the project’s prompt count); checks published before that gate stay published and can have counted fewer answers than they asked queries, so this can be lower than what that check sent. Never describe this number as the queries asked. When `latestCheckDataAvailable` is present, this count describes the earlier check the other fields came from. Null on a check recorded before we stored this count, and on such a check every rate and score that divides by it is null too — so there is nothing to divide and nothing to misread. Nullable.
`totalEntries`	`number`	Total brand entries across this check’s counted answers. Also the size preview for `includeAnswers=true`: an entry serializes to roughly 200 tokens, so a 60-entry check runs around 12k tokens unfiltered, while `brand=` returns about one entry per answer and lands nearer 2k.
`competitorRankings`	`array<object>`	Per-competitor ranking data. See `item.summary.competitorRankings[]`.

item.latestCheckDataAvailable — object

Field	Type	Description
`available`	`boolean`	Always false. This object exists only to say the most recent check produced nothing publishable.
`reason`	`string`	Why the most recent check produced nothing. `incomplete_coverage` — we did not end up with a usable answer for every query it asked. Values: `incomplete_coverage`.
`measuredAnswers`	`number \| null`	Answers that did come back usable in that check, or null on a check that predates the recorded query count. NOT a visibility figure — a check can be fully covered and still score zero. Nullable.
`expectedAnswers`	`number \| null`	Answers that check asked for: 3 AI providers x the project’s prompt count. The shortfall (expectedAnswers - measuredAnswers) is what did not arrive. Null on a check that predates the recorded query count — say the check did not complete and give no numbers. Never treat a null as 0: the subtraction would report no shortfall on a cycle that measurably failed. Nullable.

item.answers[] — each entry

Field	Type	Description
`provider`	`string`	Which AI produced this answer. Values: `openai`, `claude`, `gemini`.
`promptIndex`	`number`	Zero-based index of the project prompt this answer belongs to. The same index the summary’s per-prompt breakdown uses. Stable under filtering.
`promptText`	`string`	The exact prompt sent to the model — one of the project’s own AI prompts.
`brands`	`array<object>`	Brands this model named, in the order it ranked them. Every answer in this array arrived — a query that produced nothing is not here at all, it is in `unansweredQueries`. So an EMPTY list is a measurement, never missing data: under a `brand` filter it means this model answered this question and did not name that domain, which is a real competitive finding and often the most actionable row in the response. Unfiltered it would mean the model named nobody at all. Report an empty list as ‘this model answered and did not name them’; NEVER as ‘no data’, ‘we could not measure’, or a query that failed. See `item.answers[].brands[]`.

item.unansweredQueries[] — each entry

Field	Type	Description
`provider`	`string`	Which AI this query was sent to. Values: `openai`, `claude`, `gemini`.
`promptIndex`	`number`	Zero-based index of the project prompt this query was sent for.
`promptText`	`string`	The exact prompt that was sent.
`reason`	`string`	`no_usable_answer` — we sent this query and did not end up with an answer we could use. It names no actor and makes no claim about the prompt or the model. Report it as ‘no usable answer from this provider for this prompt — not counted’. NEVER report it as ‘not mentioned’, ‘0 mentions’ or ‘didn’t appear’, and never attach ‘failed’ to the prompt, which the customer authored. This query is excluded from every count and rate on this response. Values: `no_usable_answer`.

item.providerStatus — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT). See `item.providerStatus.openai`.
`claude`	`object`	Anthropic (Claude). See `item.providerStatus.claude`.
`gemini`	`object`	Google (Gemini). See `item.providerStatus.gemini`.

item.answerCoverage — object

Field	Type	Description
`queriesSent`	`number`	Queries this check sent: 3 AI providers x the prompt count stored on this check. Always read it from the check — do not assume 9. Checks keep the prompt count they were run with, and that count has not always been the same across a project’s history.
`answersCounted`	`number`	Queries that came back with an answer we could use. The shortfall (`queriesSent` - `answersCounted`) is what did not arrive. On a check published under the full-coverage gate that shortfall equals the length of `unansweredQueries`; on older checks it can exceed it, because a model that failed before answering anything recorded no query slots to list. Trust the shortfall, not the array length. NEVER present these two numbers as a fraction: this dimension’s headline metric is already an n-of-N over the same denominator, so ‘8 of 9’ gets read as a visibility rate. State them as separate facts that cannot be divided by each other — “We sent all 9 queries, but 1 answer didn’t come back.” Always computed over the whole check, never over a filtered view.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number \| null`	Mention rate as a percentage: mentions / `totalQueries` * 100. The divisor is this check’s own ANSWER count — the queries that came back with a usable answer — never a fixed 9. Under the full-coverage gate (a check publishes only if every query it asked returned a usable answer) that equals 3 AI providers x the project’s prompt count; checks published before that gate stay published and can have counted fewer answers than they asked queries, and the queries-sent figure is not on this response. So this is a share of the answers counted, never a share of the queries asked — do not report it as ‘mentioned in X% of AI queries’. Null when the check never recorded its answer count: with no denominator there is no rate, and the stored figure was divided by something unknown. A `0` is a real rate and means the models named this brand nowhere. Nullable.
`avgRank`	`number \| null`	Average rank across all providers and prompts (lower is better). Nullable.
`mentionCount`	`number`	Number of this check’s counted ANSWERS that mentioned the customer, out of `totalQueries`. Not out of the queries sent — that figure is not on this response.
`aiScore`	`number \| null`	AI Visibility Score — weighted 0-100 composite score. Null on checks recorded before this score existed: say the check has no score rather than reporting one. A `0` is a real score and means the brand was named nowhere we looked; a null means we never computed one. Nullable.
`perProvider`	`object`	Per-provider breakdown. See `item.summary.customer.perProvider`.
`perPrompt`	`array<object>`	How the customer did on each of the project’s prompts individually, across the models that answered. The cheap way to answer ‘which of my questions am I losing on’ — a few small rows, no need to request the raw answers block. Present only on checks that recorded how many prompts they asked: older checks stored a fixed three rows whatever the project actually ran, so those are omitted rather than published as prompts that may never have existed. Absent therefore means ‘not available for this check’, never ‘this project has no prompts’ — and the array length is this check’s real prompt count wherever it is present. See `item.summary.customer.perPrompt[]`.

item.summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain
`name`	`string`	Top competitor brand name
`mentionRate`	`number \| null`	Top competitor mention rate percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. Null on the same condition and for the same reason: no recorded answer count means no denominator, so there is no rate to report. Nullable.
`avgRank`	`number \| null`	Top competitor average rank (lower is better). Nullable.

item.summary.competitorRankings[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across the answers this check counted.
`mentionRate`	`number \| null`	Mention rate as percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. Null when that count was never recorded. This row names a THIRD PARTY, so a fabricated rate here is a claim about another company published under our name. Nullable.
`aiScore`	`number \| null`	AI Visibility Score (0-100), or null on checks recorded before this score existed. This one names a THIRD PARTY, so the distinction matters more here than anywhere else on the response: a `0` says the models never mentioned this competitor, a null says we have no score for them. Reporting a null as `0` publishes a false claim about another company under our name. Nullable.
`isTracked`	`boolean`	Whether this domain is one the project currently monitors, as opposed to one an AI named on its own. Resolved against the project’s CURRENT competitor list, so on a historical check it describes today’s roster and not the roster at the time of that check — it is not a fact about the check. The customer’s own row is always `true`; see `isOwn` to identify it.

item.answers[].brands[] — each entry

Field	Type	Description
`rank`	`number`	Position in this model’s ranked answer — 1 means named first. This is the rank among the brands recorded for this answer: brands are de-duplicated by domain before storage, so it is the position as recorded rather than necessarily the ordinal the model itself emitted. Stable under filtering — narrowing by `provider`, `brand` or `promptIndex` never renumbers it.
`name`	`string`	Brand name as the model wrote it.
`domain`	`string`	Brand domain, normalized.
`description`	`string`	One-sentence description of the brand, in the model’s own words.
`rankingRationale`	`string`	The model’s stated reason for placing this brand where it did. The single most useful field here for understanding WHY a ranking looks the way it does — and the model’s reasoning, not a verified fact.
`sentiment`	`string`	How warmly the model spoke about this brand in this answer. Values: `highly_recommended`, `recommended`, `mentioned`, `alternative`.
`mentionContext`	`string`	The role this brand played in the answer. Values: `direct_recommendation`, `comparison`, `alternative`, `niche_fit`.
`targetAudience`	`string`	Who the model said this brand is for.
`pricingSignal`	`string`	The price tier the model placed this brand in. Values: `free`, `budget`, `mid_range`, `premium`, `enterprise`, `unknown`.
`positionConfidence`	`number`	0-1. How confidently this brand’s position could be read out of the model’s answer. It is not a measure of whether the model’s ranking is correct.
`features`	`array<string>`	Features the model highlighted for this brand (max 5).
`differentiation`	`object`	How the model framed this brand’s differentiation. See `item.answers[].brands[].differentiation`.
`messaging`	`object`	The messaging the model associated with this brand. See `item.answers[].brands[].messaging`.

item.providerStatus.openai — object

Field	Type	Description
`reported`	`boolean`	Whether this model produced a result record for this check. `false` means nothing came back from it at all. `true` does NOT mean it answered usefully: a model can be asked and have every one of its queries come back unusable, which appears here as `reported: true` with `answersCounted: 0`. Read the pair. `answersCounted: 0` means we got no usable answer from this model — NEVER that it answered and named nobody. Those queries are listed in `unansweredQueries`.
`completedAt`	`string \| null`	When this model finished (ISO-8601). Null when it never reported. Nullable.
`answersCounted`	`number`	Queries to this model that came back with an answer we could use. This is the discriminator to read `reported` and `brandsNamed` against.
`brandsNamed`	`number`	Brand entries this model named across the answers that came back, counting a brand once per answer it appears in. `0` beside `answersCounted: 0` means this model produced no usable answer — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.claude — object

Field	Type	Description
`reported`	`boolean`	Whether this model produced a result record for this check. `false` means nothing came back from it at all. `true` does NOT mean it answered usefully: a model can be asked and have every one of its queries come back unusable, which appears here as `reported: true` with `answersCounted: 0`. Read the pair. `answersCounted: 0` means we got no usable answer from this model — NEVER that it answered and named nobody. Those queries are listed in `unansweredQueries`.
`completedAt`	`string \| null`	When this model finished (ISO-8601). Null when it never reported. Nullable.
`answersCounted`	`number`	Queries to this model that came back with an answer we could use. This is the discriminator to read `reported` and `brandsNamed` against.
`brandsNamed`	`number`	Brand entries this model named across the answers that came back, counting a brand once per answer it appears in. `0` beside `answersCounted: 0` means this model produced no usable answer — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.gemini — object

Field	Type	Description
`reported`	`boolean`	Whether this model produced a result record for this check. `false` means nothing came back from it at all. `true` does NOT mean it answered usefully: a model can be asked and have every one of its queries come back unusable, which appears here as `reported: true` with `answersCounted: 0`. Read the pair. `answersCounted: 0` means we got no usable answer from this model — NEVER that it answered and named nobody. Those queries are listed in `unansweredQueries`.
`completedAt`	`string \| null`	When this model finished (ISO-8601). Null when it never reported. Nullable.
`answersCounted`	`number`	Queries to this model that came back with an answer we could use. This is the discriminator to read `reported` and `brandsNamed` against.
`brandsNamed`	`number`	Brand entries this model named across the answers that came back, counting a brand once per answer it appears in. `0` beside `answersCounted: 0` means this model produced no usable answer — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT) metrics. Nested — see the Example tab.
`claude`	`object`	Anthropic (Claude) metrics. Nested — see the Example tab.
`gemini`	`object`	Google (Gemini) metrics. Nested — see the Example tab.

item.summary.customer.perPrompt[] — each entry

Field	Type	Description
`promptIndex`	`number`	Zero-based index of this prompt, matching `promptIndex` on `answers[]` and the `promptIndex` filter.
`promptLabel`	`string`	Short label for the prompt, truncated to 80 characters, falling back to a ONE-BASED `Prompt N` placeholder when no text was captured — so `promptIndex: 0` labels as ‘Prompt 1’. Quote the label to a human and the index to this API; do not read a number out of the label and pass it as `promptIndex`. A display label, not the prompt — the full text is on `answers[].promptText`, and the project’s current prompts are on the project endpoint.
`mentionedBy`	`array<string>`	Models that named the customer for this prompt. A model is listed only when it genuinely ranked them, so this is safe to read positively. Reading it negatively needs the usual care: a model missing from the list did not name the customer in the answers this check counted — under the full-coverage gate that is a measured absence, but on a check published before that gate it could be an answer that never arrived.
`score`	`number`	0-100 weighted position score for this prompt, averaged over the models whose answers this check counted — never over a fixed 3. Higher is better, and it rewards top positions steeply rather than linearly, so it is not a rank and not a percentage of anything. `mentionedBy` is the tell for reading a `0`: non-empty means the score is real. If `mentionedBy` is empty and you need certainty, fetch `includeAnswers=true&promptIndex=<n>` — a prompt that was answered and did not rank the customer has entries in `answers`, while one that was never measured is in `unansweredQueries`.

item.answers[].brands[].differentiation — object

Field	Type	Description
`axis`	`string`	The axis the model framed this brand as competing on. Values: `technology`, `price`, `service`, `speed`, `scale`.
`uniqueValue`	`string`	What the model said sets this brand apart, in its own words. The model’s claim, not a verified fact.

item.answers[].brands[].messaging — object

Field	Type	Description
`keywords`	`array<string>`	Keywords the model associated with this brand (up to 5).
`credibilitySignals`	`array<string>`	Claims the model offered as evidence for this brand — certifications, customer counts, awards. The model asserts these; it does not source them and CompetLab does not verify them.
`differentiationClaims`	`array<string>`	Differentiation claims the model attributed to this brand (up to 3). The model’s claims about the brand, not verified facts.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`project_not_found` · `no_data_available`	No `project` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Get AI visibility check history

GET/v1/projects/{projectId}/ai-visibility/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. Only scored checks are listed — under the full-coverage gate a cycle that came back short is never scored and does not appear here. 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.

Returns · { items, pagination, truncated }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Required	Description
`page`	`number`		Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`		Number of items per page. Default `20`. Range `1`–`100`.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility/history?page=1&limit=20" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "checkId": "507f1f77bcf86cd799439011",
      "completedAt": "2026-03-15T10:00:00.000Z",
      "summary": {
        "customer": {
          "domain": "mycompany.com",
          "mentionRate": 66.7,
          "avgRank": 2.5,
          "mentionCount": 6,
          "aiScore": 73,
          "perProvider": {
            "openai": {
              "rank": 2.3,
              "mentioned": true,
              "mentionCount": 3
            },
            "claude": {
              "rank": 2.3,
              "mentioned": true,
              "mentionCount": 3
            },
            "gemini": {
              "rank": 2.3,
              "mentioned": true,
              "mentionCount": 3
            }
          },
          "perPrompt": [
            {
              "promptIndex": 0,
              "promptLabel": "best sales forecasting platforms for mid-market teams",
              "mentionedBy": [
                "openai",
                "claude"
              ],
              "score": 61
            }
          ]
        },
        "topCompetitor": {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "mentionRate": 88.9,
          "avgRank": 1.8
        },
        "mentionRateGap": -22.2,
        "totalCompetitorsFound": 8,
        "totalQueries": 9,
        "totalEntries": 45,
        "competitorRankings": [
          {
            "domain": "competitor.com",
            "name": "Competitor Inc",
            "isOwn": false,
            "openaiAvgRank": 2,
            "claudeAvgRank": 1.7,
            "geminiAvgRank": 3,
            "overallAvgRank": 2.2,
            "mentionCount": 7,
            "mentionRate": 77.8,
            "aiScore": 68,
            "isTracked": false
          }
        ]
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 47,
    "totalPages": 3,
    "hasMore": true
  },
  "truncated": false
}

Fields

items[] — each entry

Field	Type	Description
`checkId`	`string`	Check ID
`completedAt`	`string`	When this check completed (ISO-8601)
`summary`	`object`	Check summary statistics. See `items[].summary`.

pagination — object

Field	Type	Description
`page`	`number`	Current page number (1-indexed)
`limit`	`number`	Number of items per page
`total`	`number`	Total number of items across all pages
`totalPages`	`number`	Total number of pages
`hasMore`	`boolean`	Whether more pages exist after the current page

items[].summary — object

Field	Type	Description
`customer`	`object`	Customer metrics. See `items[].summary.customer`.
`topCompetitor`	`object \| null`	Top competitor by mention rate. Nullable. See `items[].summary.topCompetitor`.
`mentionRateGap`	`number \| null`	Gap between customer and top competitor mention rate (negative means customer is behind), or null when this check found no competitor to compare against — `topCompetitor` is null on the same response. A `0` means genuinely level; a null means there was nobody to be level with. Nullable.
`totalCompetitorsFound`	`number`	Total unique competitors found across AI responses
`totalQueries`	`number \| null`	Answers this check counted — the queries that came back with a usable answer. Despite the field name this is NOT the number of queries sent; that figure is not on this response and cannot be derived from it. This is the divisor of every rate and score here. Under the full-coverage gate the two are equal (3 AI providers x the project’s prompt count); checks published before that gate stay published and can have counted fewer answers than they asked queries, so this can be lower than what that check sent. Never describe this number as the queries asked. When `latestCheckDataAvailable` is present, this count describes the earlier check the other fields came from. Null on a check recorded before we stored this count, and on such a check every rate and score that divides by it is null too — so there is nothing to divide and nothing to misread. Nullable.
`totalEntries`	`number`	Total brand entries across this check’s counted answers. Also the size preview for `includeAnswers=true`: an entry serializes to roughly 200 tokens, so a 60-entry check runs around 12k tokens unfiltered, while `brand=` returns about one entry per answer and lands nearer 2k.
`competitorRankings`	`array<object>`	Per-competitor ranking data. See `items[].summary.competitorRankings[]`.

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number \| null`	Mention rate as a percentage: mentions / `totalQueries` * 100. The divisor is this check’s own ANSWER count — the queries that came back with a usable answer — never a fixed 9. Under the full-coverage gate (a check publishes only if every query it asked returned a usable answer) that equals 3 AI providers x the project’s prompt count; checks published before that gate stay published and can have counted fewer answers than they asked queries, and the queries-sent figure is not on this response. So this is a share of the answers counted, never a share of the queries asked — do not report it as ‘mentioned in X% of AI queries’. Null when the check never recorded its answer count: with no denominator there is no rate, and the stored figure was divided by something unknown. A `0` is a real rate and means the models named this brand nowhere. Nullable.
`avgRank`	`number \| null`	Average rank across all providers and prompts (lower is better). Nullable.
`mentionCount`	`number`	Number of this check’s counted ANSWERS that mentioned the customer, out of `totalQueries`. Not out of the queries sent — that figure is not on this response.
`aiScore`	`number \| null`	AI Visibility Score — weighted 0-100 composite score. Null on checks recorded before this score existed: say the check has no score rather than reporting one. A `0` is a real score and means the brand was named nowhere we looked; a null means we never computed one. Nullable.
`perProvider`	`object`	Per-provider breakdown. See `items[].summary.customer.perProvider`.
`perPrompt`	`array<object>`	How the customer did on each of the project’s prompts individually, across the models that answered. The cheap way to answer ‘which of my questions am I losing on’ — a few small rows, no need to request the raw answers block. Present only on checks that recorded how many prompts they asked: older checks stored a fixed three rows whatever the project actually ran, so those are omitted rather than published as prompts that may never have existed. Absent therefore means ‘not available for this check’, never ‘this project has no prompts’ — and the array length is this check’s real prompt count wherever it is present. See `items[].summary.customer.perPrompt[]`.

items[].summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain
`name`	`string`	Top competitor brand name
`mentionRate`	`number \| null`	Top competitor mention rate percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. Null on the same condition and for the same reason: no recorded answer count means no denominator, so there is no rate to report. Nullable.
`avgRank`	`number \| null`	Top competitor average rank (lower is better). Nullable.

items[].summary.competitorRankings[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across the answers this check counted.
`mentionRate`	`number \| null`	Mention rate as percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. Null when that count was never recorded. This row names a THIRD PARTY, so a fabricated rate here is a claim about another company published under our name. Nullable.
`aiScore`	`number \| null`	AI Visibility Score (0-100), or null on checks recorded before this score existed. This one names a THIRD PARTY, so the distinction matters more here than anywhere else on the response: a `0` says the models never mentioned this competitor, a null says we have no score for them. Reporting a null as `0` publishes a false claim about another company under our name. Nullable.
`isTracked`	`boolean`	Whether this domain is one the project currently monitors, as opposed to one an AI named on its own. Resolved against the project’s CURRENT competitor list, so on a historical check it describes today’s roster and not the roster at the time of that check — it is not a fact about the check. The customer’s own row is always `true`; see `isOwn` to identify it.

items[].summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT) metrics. Nested — see the Example tab.
`claude`	`object`	Anthropic (Claude) metrics. Nested — see the Example tab.
`gemini`	`object`	Google (Gemini) metrics. Nested — see the Example tab.

items[].summary.customer.perPrompt[] — each entry

Field	Type	Description
`promptIndex`	`number`	Zero-based index of this prompt, matching `promptIndex` on `answers[]` and the `promptIndex` filter.
`promptLabel`	`string`	Short label for the prompt, truncated to 80 characters, falling back to a ONE-BASED `Prompt N` placeholder when no text was captured — so `promptIndex: 0` labels as ‘Prompt 1’. Quote the label to a human and the index to this API; do not read a number out of the label and pass it as `promptIndex`. A display label, not the prompt — the full text is on `answers[].promptText`, and the project’s current prompts are on the project endpoint.
`mentionedBy`	`array<string>`	Models that named the customer for this prompt. A model is listed only when it genuinely ranked them, so this is safe to read positively. Reading it negatively needs the usual care: a model missing from the list did not name the customer in the answers this check counted — under the full-coverage gate that is a measured absence, but on a check published before that gate it could be an answer that never arrived.
`score`	`number`	0-100 weighted position score for this prompt, averaged over the models whose answers this check counted — never over a fixed 3. Higher is better, and it rewards top positions steeply rather than linearly, so it is not a rank and not a percentage of anything. `mentionedBy` is the tell for reading a `0`: non-empty means the score is real. If `mentionedBy` is empty and you need certainty, fetch `includeAnswers=true&promptIndex=<n>` — a prompt that was answered and did not rank the customer has entries in `answers`, while one that was never measured is in `unansweredQueries`.

Paginated — pass page and limit query parameters and follow pagination.hasMore to page through the full set.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}

Get AI visibility data for a specific check

GET/v1/projects/{projectId}/ai-visibility/history/{checkId}

Get full AI visibility data for a specific historical check: per-competitor rankings across all three AI providers, with mention rates and AI Visibility Scores, under summary. Rates here divide by the answers that came back, not the queries sent, and the queries-sent figure is not on summary — describe a rate as a share of the answers counted, never as a share of every query asked. Set includeAnswers=true to also get what the models actually said: every prompt sent, and every brand each model named in rank order with its stated reasoning, plus providerStatus and (where the check recorded its ask) answerCoverage. That block is large — roughly 12k tokens unfiltered, against roughly 2k with brand=. Check summary.totalEntries to size it first (about 200 tokens per entry), and prefer brand=<domain> (one competitor across every answer) or provider= (one model) over fetching everything; promptIndex= narrows to a single prompt. provider and promptIndex narrow the answers array; brand does not — it reduces the brands list inside each answer, so every answer still comes back and the ones that did not name that domain arrive with an empty brands, which is a finding rather than an absence. No filter changes any number under summary: those are stored, computed over the whole check, and never recomputed for a filtered view. Ranks are stable under filtering. Queries that produced no usable answer are listed separately in unansweredQueries rather than appearing as answers naming nobody — those are different facts, and an empty brands under a brand filter is NOT that case. summary.customer.perPrompt, when present, breaks the customer’s result down per prompt at no extra cost — use it before reaching for includeAnswers.

Returns · { item }

Path parameters

Name	Type	Description
`checkId`	`string`	Check ID
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`includeAnswers`	`boolean`	Set true to include the models’ raw answers — every prompt sent and every brand each model named, with its stated reasoning. Off by default because the block is large: roughly 12k tokens unfiltered, against roughly 2k with `brand=`. Read `summary.totalEntries` to size it first (about 200 tokens per entry). The prose it returns is the model’s wording about the brands it named, not CompetLab’s assessment. Default `false`.
`provider`	`string`	Return only this model’s answers. Requires `includeAnswers=true`. Does not change any number under `summary`, and does not narrow `providerStatus`. Values: `openai`, `claude`, `gemini`.
`brand`	`string`	Return only the entries for this domain, across every answer. Requires `includeAnswers=true`. Matches `brands[].domain`, case-insensitively; brand NAMES are the model’s own wording and vary between answers, so they are never matched. EVERY answer is still returned — the ones that did not name this domain come back with an empty `brands`, because ‘this model answered and did not name them’ is a finding, not an absence of data. A query that produced no answer at all is in `unansweredQueries` instead and asserts nothing about anyone. Ranks are unaffected: an entry keeps the position it held in the full answer. This is the cheapest way to ask where a competitor wins and where they are invisible.
`promptIndex`	`number`	Return only the answers for this prompt, across every model. Requires `includeAnswers=true`. Zero-based, matching the per-prompt index used elsewhere in this dimension.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility/history/507f1f77bcf86cd799439012?includeAnswers=false&provider=openai&brand=competitor.com&promptIndex=0" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "item": {
    "checkId": "507f1f77bcf86cd799439011",
    "completedAt": "2026-03-15T10:00:00.000Z",
    "summary": {
      "customer": {
        "domain": "mycompany.com",
        "mentionRate": 66.7,
        "avgRank": 2.5,
        "mentionCount": 6,
        "aiScore": 73,
        "perProvider": {
          "openai": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "claude": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          },
          "gemini": {
            "rank": 2.3,
            "mentioned": true,
            "mentionCount": 3
          }
        },
        "perPrompt": [
          {
            "promptIndex": 0,
            "promptLabel": "best sales forecasting platforms for mid-market teams",
            "mentionedBy": [
              "openai",
              "claude"
            ],
            "score": 61
          }
        ]
      },
      "topCompetitor": {
        "domain": "competitor.com",
        "name": "Competitor Inc",
        "mentionRate": 88.9,
        "avgRank": 1.8
      },
      "mentionRateGap": -22.2,
      "totalCompetitorsFound": 8,
      "totalQueries": 9,
      "totalEntries": 45,
      "competitorRankings": [
        {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "isOwn": false,
          "openaiAvgRank": 2,
          "claudeAvgRank": 1.7,
          "geminiAvgRank": 3,
          "overallAvgRank": 2.2,
          "mentionCount": 7,
          "mentionRate": 77.8,
          "aiScore": 68,
          "isTracked": false
        }
      ]
    },
    "answers": [
      {
        "provider": "openai",
        "promptIndex": 0,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "brands": [
          {
            "rank": 1,
            "name": "Competitor Inc",
            "domain": "competitor.com",
            "description": "Cloud platform for pipeline forecasting aimed at mid-market sales teams.",
            "rankingRationale": "Listed first because it integrates directly with the major CRMs.",
            "sentiment": "recommended",
            "mentionContext": "direct_recommendation",
            "targetAudience": "Mid-size B2B sales teams",
            "pricingSignal": "mid_range",
            "positionConfidence": 0.9,
            "features": [
              "pipeline forecasting",
              "CRM sync"
            ],
            "differentiation": {
              "axis": "technology",
              "uniqueValue": "Only platform with native two-way CRM sync"
            },
            "messaging": {
              "keywords": [
                "automation",
                "mid-market",
                "self-serve"
              ],
              "credibilitySignals": [
                "SOC 2 Type II",
                "used by 400+ teams"
              ],
              "differentiationClaims": [
                "fastest setup in category"
              ]
            }
          }
        ]
      }
    ],
    "unansweredQueries": [
      {
        "provider": "gemini",
        "promptIndex": 2,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "reason": "no_usable_answer"
      }
    ],
    "providerStatus": {
      "openai": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "brandsNamed": 21
      },
      "claude": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "brandsNamed": 21
      },
      "gemini": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "brandsNamed": 21
      }
    },
    "answerCoverage": {
      "queriesSent": 9,
      "answersCounted": 8
    },
    "answersTruncated": false
  }
}

Fields

item — object

Field	Type	Description
`checkId`	`string`	Check ID
`completedAt`	`string`	When this check completed (ISO-8601)
`summary`	`object`	Check summary statistics, including this check’s per-competitor rankings under `summary.competitorRankings`. See `item.summary`.
`answers`	`array<object>`	The models’ answers for this check — one entry per query that came back with an answer we could use. Present ONLY when the request set `includeAnswers=true`; absent otherwise, never an empty array standing in for ‘not requested’. Narrowed by `provider` and `promptIndex` when those are set — those also narrow the matching entries of `unansweredQueries`. `brand` narrows DIFFERENTLY: it reduces the `brands` list inside each answer and never this array, so every answer the check counted is still here and the ones that did not name that domain arrive with an empty `brands`. `brand` narrows `unansweredQueries` not at all, because a query that produced no answer could have named anyone. No filter changes anything else: every number under `summary` is stored, computed over the whole check, and is never recomputed for a filtered view. ATTRIBUTION: every piece of prose in this block — descriptions, ranking rationales, audiences, claims — is unverified model output about the brands that model named, including third parties CompetLab does not monitor. It is a record of what the model said, not CompetLab’s assessment of those brands. Attribute it to the named `provider`; do not republish it as fact. See `item.answers[]`.
`unansweredQueries`	`array<object>`	Queries this check sent that produced no usable answer. Present ONLY when `includeAnswers=true`. Carried in their own array rather than mixed into `answers` so that `answers.length` always means answers counted and can never be read as queries sent. An empty array means every query this check sent came back — which is the normal case, because a check is only scored when it got a usable answer to every query it asked. It can be non-empty on checks published before that rule existed. These queries are excluded from every count and rate on this response. Never pair this array’s length with `summary.totalQueries` as a fraction. `totalQueries` counts answers, this counts queries that produced none, and adding them recovers the queries sent — but ‘8 of 9’ beside this dimension’s headline metric gets read as a visibility rate. State them as separate facts that cannot be divided by each other. See `item.unansweredQueries[]`.
`providerStatus`	`object`	Per-model reporting status for this check: which of the three models returned data, when, and how much. Present ONLY when `includeAnswers=true`. It carries no visibility judgement, and it is NOT narrowed by the filters — it always describes all three models across the whole check, so a filtered response still says what the full picture was. See `item.providerStatus`.
`answerCoverage`	`object`	How many queries this check sent, and how many came back. Present ONLY when `includeAnswers=true` AND the check recorded the number it sent. Absent on checks written before that count was recorded — there the figure is genuinely unknown and must not be inferred, least of all from the length of `answers`. Always describes the whole check, never a filtered view. Report the two numbers as separate facts, never as a fraction — see `answersCounted`. See `item.answerCoverage`.
`answersTruncated`	`boolean`	True when the answers payload hit the response size cap and whole answers were dropped from the end of `answers`. Individual `brands` lists are never partially truncated — a half-truncated ranked list would be a wrong list, not a short one. `summary`, `providerStatus` and `answerCoverage` are never affected. Narrow the response with `provider`, `brand` or `promptIndex` to get a complete view. Present ONLY when `includeAnswers=true`.

item.summary — object

Field	Type	Description
`customer`	`object`	Customer metrics. See `item.summary.customer`.
`topCompetitor`	`object \| null`	Top competitor by mention rate. Nullable. See `item.summary.topCompetitor`.
`mentionRateGap`	`number \| null`	Gap between customer and top competitor mention rate (negative means customer is behind), or null when this check found no competitor to compare against — `topCompetitor` is null on the same response. A `0` means genuinely level; a null means there was nobody to be level with. Nullable.
`totalCompetitorsFound`	`number`	Total unique competitors found across AI responses
`totalQueries`	`number \| null`	Answers this check counted — the queries that came back with a usable answer. Despite the field name this is NOT the number of queries sent; that figure is not on this response and cannot be derived from it. This is the divisor of every rate and score here. Under the full-coverage gate the two are equal (3 AI providers x the project’s prompt count); checks published before that gate stay published and can have counted fewer answers than they asked queries, so this can be lower than what that check sent. Never describe this number as the queries asked. When `latestCheckDataAvailable` is present, this count describes the earlier check the other fields came from. Null on a check recorded before we stored this count, and on such a check every rate and score that divides by it is null too — so there is nothing to divide and nothing to misread. Nullable.
`totalEntries`	`number`	Total brand entries across this check’s counted answers. Also the size preview for `includeAnswers=true`: an entry serializes to roughly 200 tokens, so a 60-entry check runs around 12k tokens unfiltered, while `brand=` returns about one entry per answer and lands nearer 2k.
`competitorRankings`	`array<object>`	Per-competitor ranking data. See `item.summary.competitorRankings[]`.

item.answers[] — each entry

Field	Type	Description
`provider`	`string`	Which AI produced this answer. Values: `openai`, `claude`, `gemini`.
`promptIndex`	`number`	Zero-based index of the project prompt this answer belongs to. The same index the summary’s per-prompt breakdown uses. Stable under filtering.
`promptText`	`string`	The exact prompt sent to the model — one of the project’s own AI prompts.
`brands`	`array<object>`	Brands this model named, in the order it ranked them. Every answer in this array arrived — a query that produced nothing is not here at all, it is in `unansweredQueries`. So an EMPTY list is a measurement, never missing data: under a `brand` filter it means this model answered this question and did not name that domain, which is a real competitive finding and often the most actionable row in the response. Unfiltered it would mean the model named nobody at all. Report an empty list as ‘this model answered and did not name them’; NEVER as ‘no data’, ‘we could not measure’, or a query that failed. See `item.answers[].brands[]`.

item.unansweredQueries[] — each entry

Field	Type	Description
`provider`	`string`	Which AI this query was sent to. Values: `openai`, `claude`, `gemini`.
`promptIndex`	`number`	Zero-based index of the project prompt this query was sent for.
`promptText`	`string`	The exact prompt that was sent.
`reason`	`string`	`no_usable_answer` — we sent this query and did not end up with an answer we could use. It names no actor and makes no claim about the prompt or the model. Report it as ‘no usable answer from this provider for this prompt — not counted’. NEVER report it as ‘not mentioned’, ‘0 mentions’ or ‘didn’t appear’, and never attach ‘failed’ to the prompt, which the customer authored. This query is excluded from every count and rate on this response. Values: `no_usable_answer`.

item.providerStatus — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT). See `item.providerStatus.openai`.
`claude`	`object`	Anthropic (Claude). See `item.providerStatus.claude`.
`gemini`	`object`	Google (Gemini). See `item.providerStatus.gemini`.

item.answerCoverage — object

Field	Type	Description
`queriesSent`	`number`	Queries this check sent: 3 AI providers x the prompt count stored on this check. Always read it from the check — do not assume 9. Checks keep the prompt count they were run with, and that count has not always been the same across a project’s history.
`answersCounted`	`number`	Queries that came back with an answer we could use. The shortfall (`queriesSent` - `answersCounted`) is what did not arrive. On a check published under the full-coverage gate that shortfall equals the length of `unansweredQueries`; on older checks it can exceed it, because a model that failed before answering anything recorded no query slots to list. Trust the shortfall, not the array length. NEVER present these two numbers as a fraction: this dimension’s headline metric is already an n-of-N over the same denominator, so ‘8 of 9’ gets read as a visibility rate. State them as separate facts that cannot be divided by each other — “We sent all 9 queries, but 1 answer didn’t come back.” Always computed over the whole check, never over a filtered view.

item.summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number \| null`	Mention rate as a percentage: mentions / `totalQueries` * 100. The divisor is this check’s own ANSWER count — the queries that came back with a usable answer — never a fixed 9. Under the full-coverage gate (a check publishes only if every query it asked returned a usable answer) that equals 3 AI providers x the project’s prompt count; checks published before that gate stay published and can have counted fewer answers than they asked queries, and the queries-sent figure is not on this response. So this is a share of the answers counted, never a share of the queries asked — do not report it as ‘mentioned in X% of AI queries’. Null when the check never recorded its answer count: with no denominator there is no rate, and the stored figure was divided by something unknown. A `0` is a real rate and means the models named this brand nowhere. Nullable.
`avgRank`	`number \| null`	Average rank across all providers and prompts (lower is better). Nullable.
`mentionCount`	`number`	Number of this check’s counted ANSWERS that mentioned the customer, out of `totalQueries`. Not out of the queries sent — that figure is not on this response.
`aiScore`	`number \| null`	AI Visibility Score — weighted 0-100 composite score. Null on checks recorded before this score existed: say the check has no score rather than reporting one. A `0` is a real score and means the brand was named nowhere we looked; a null means we never computed one. Nullable.
`perProvider`	`object`	Per-provider breakdown. See `item.summary.customer.perProvider`.
`perPrompt`	`array<object>`	How the customer did on each of the project’s prompts individually, across the models that answered. The cheap way to answer ‘which of my questions am I losing on’ — a few small rows, no need to request the raw answers block. Present only on checks that recorded how many prompts they asked: older checks stored a fixed three rows whatever the project actually ran, so those are omitted rather than published as prompts that may never have existed. Absent therefore means ‘not available for this check’, never ‘this project has no prompts’ — and the array length is this check’s real prompt count wherever it is present. See `item.summary.customer.perPrompt[]`.

item.summary.topCompetitor — object

Field	Type	Description
`domain`	`string`	Top competitor domain
`name`	`string`	Top competitor brand name
`mentionRate`	`number \| null`	Top competitor mention rate percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. Null on the same condition and for the same reason: no recorded answer count means no denominator, so there is no rate to report. Nullable.
`avgRank`	`number \| null`	Top competitor average rank (lower is better). Nullable.

item.summary.competitorRankings[] — each entry

Field	Type	Description
`domain`	`string`	Competitor domain
`name`	`string`	Competitor brand name
`isOwn`	`boolean`	Whether this is the customer own domain
`openaiAvgRank`	`number \| null`	Average rank in OpenAI responses (lower is better). Nullable.
`claudeAvgRank`	`number \| null`	Average rank in Claude responses (lower is better). Nullable.
`geminiAvgRank`	`number \| null`	Average rank in Gemini responses (lower is better). Nullable.
`overallAvgRank`	`number \| null`	Overall average rank across all providers (lower is better). Nullable.
`mentionCount`	`number`	Total mentions across the answers this check counted.
`mentionRate`	`number \| null`	Mention rate as percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. Null when that count was never recorded. This row names a THIRD PARTY, so a fabricated rate here is a claim about another company published under our name. Nullable.
`aiScore`	`number \| null`	AI Visibility Score (0-100), or null on checks recorded before this score existed. This one names a THIRD PARTY, so the distinction matters more here than anywhere else on the response: a `0` says the models never mentioned this competitor, a null says we have no score for them. Reporting a null as `0` publishes a false claim about another company under our name. Nullable.
`isTracked`	`boolean`	Whether this domain is one the project currently monitors, as opposed to one an AI named on its own. Resolved against the project’s CURRENT competitor list, so on a historical check it describes today’s roster and not the roster at the time of that check — it is not a fact about the check. The customer’s own row is always `true`; see `isOwn` to identify it.

item.answers[].brands[] — each entry

Field	Type	Description
`rank`	`number`	Position in this model’s ranked answer — 1 means named first. This is the rank among the brands recorded for this answer: brands are de-duplicated by domain before storage, so it is the position as recorded rather than necessarily the ordinal the model itself emitted. Stable under filtering — narrowing by `provider`, `brand` or `promptIndex` never renumbers it.
`name`	`string`	Brand name as the model wrote it.
`domain`	`string`	Brand domain, normalized.
`description`	`string`	One-sentence description of the brand, in the model’s own words.
`rankingRationale`	`string`	The model’s stated reason for placing this brand where it did. The single most useful field here for understanding WHY a ranking looks the way it does — and the model’s reasoning, not a verified fact.
`sentiment`	`string`	How warmly the model spoke about this brand in this answer. Values: `highly_recommended`, `recommended`, `mentioned`, `alternative`.
`mentionContext`	`string`	The role this brand played in the answer. Values: `direct_recommendation`, `comparison`, `alternative`, `niche_fit`.
`targetAudience`	`string`	Who the model said this brand is for.
`pricingSignal`	`string`	The price tier the model placed this brand in. Values: `free`, `budget`, `mid_range`, `premium`, `enterprise`, `unknown`.
`positionConfidence`	`number`	0-1. How confidently this brand’s position could be read out of the model’s answer. It is not a measure of whether the model’s ranking is correct.
`features`	`array<string>`	Features the model highlighted for this brand (max 5).
`differentiation`	`object`	How the model framed this brand’s differentiation. See `item.answers[].brands[].differentiation`.
`messaging`	`object`	The messaging the model associated with this brand. See `item.answers[].brands[].messaging`.

item.providerStatus.openai — object

Field	Type	Description
`reported`	`boolean`	Whether this model produced a result record for this check. `false` means nothing came back from it at all. `true` does NOT mean it answered usefully: a model can be asked and have every one of its queries come back unusable, which appears here as `reported: true` with `answersCounted: 0`. Read the pair. `answersCounted: 0` means we got no usable answer from this model — NEVER that it answered and named nobody. Those queries are listed in `unansweredQueries`.
`completedAt`	`string \| null`	When this model finished (ISO-8601). Null when it never reported. Nullable.
`answersCounted`	`number`	Queries to this model that came back with an answer we could use. This is the discriminator to read `reported` and `brandsNamed` against.
`brandsNamed`	`number`	Brand entries this model named across the answers that came back, counting a brand once per answer it appears in. `0` beside `answersCounted: 0` means this model produced no usable answer — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.claude — object

Field	Type	Description
`reported`	`boolean`	Whether this model produced a result record for this check. `false` means nothing came back from it at all. `true` does NOT mean it answered usefully: a model can be asked and have every one of its queries come back unusable, which appears here as `reported: true` with `answersCounted: 0`. Read the pair. `answersCounted: 0` means we got no usable answer from this model — NEVER that it answered and named nobody. Those queries are listed in `unansweredQueries`.
`completedAt`	`string \| null`	When this model finished (ISO-8601). Null when it never reported. Nullable.
`answersCounted`	`number`	Queries to this model that came back with an answer we could use. This is the discriminator to read `reported` and `brandsNamed` against.
`brandsNamed`	`number`	Brand entries this model named across the answers that came back, counting a brand once per answer it appears in. `0` beside `answersCounted: 0` means this model produced no usable answer — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.gemini — object

Field	Type	Description
`reported`	`boolean`	Whether this model produced a result record for this check. `false` means nothing came back from it at all. `true` does NOT mean it answered usefully: a model can be asked and have every one of its queries come back unusable, which appears here as `reported: true` with `answersCounted: 0`. Read the pair. `answersCounted: 0` means we got no usable answer from this model — NEVER that it answered and named nobody. Those queries are listed in `unansweredQueries`.
`completedAt`	`string \| null`	When this model finished (ISO-8601). Null when it never reported. Nullable.
`answersCounted`	`number`	Queries to this model that came back with an answer we could use. This is the discriminator to read `reported` and `brandsNamed` against.
`brandsNamed`	`number`	Brand entries this model named across the answers that came back, counting a brand once per answer it appears in. `0` beside `answersCounted: 0` means this model produced no usable answer — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	OpenAI (ChatGPT) metrics. Nested — see the Example tab.
`claude`	`object`	Anthropic (Claude) metrics. Nested — see the Example tab.
`gemini`	`object`	Google (Gemini) metrics. Nested — see the Example tab.

item.summary.customer.perPrompt[] — each entry

Field	Type	Description
`promptIndex`	`number`	Zero-based index of this prompt, matching `promptIndex` on `answers[]` and the `promptIndex` filter.
`promptLabel`	`string`	Short label for the prompt, truncated to 80 characters, falling back to a ONE-BASED `Prompt N` placeholder when no text was captured — so `promptIndex: 0` labels as ‘Prompt 1’. Quote the label to a human and the index to this API; do not read a number out of the label and pass it as `promptIndex`. A display label, not the prompt — the full text is on `answers[].promptText`, and the project’s current prompts are on the project endpoint.
`mentionedBy`	`array<string>`	Models that named the customer for this prompt. A model is listed only when it genuinely ranked them, so this is safe to read positively. Reading it negatively needs the usual care: a model missing from the list did not name the customer in the answers this check counted — under the full-coverage gate that is a measured absence, but on a check published before that gate it could be an answer that never arrived.
`score`	`number`	0-100 weighted position score for this prompt, averaged over the models whose answers this check counted — never over a fixed 3. Higher is better, and it rewards top positions steeply rather than linearly, so it is not a rank and not a percentage of anything. `mentionedBy` is the tell for reading a `0`: non-empty means the score is real. If `mentionedBy` is empty and you need certainty, fetch `includeAnswers=true&promptIndex=<n>` — a prompt that was answered and did not rank the customer has entries in `answers`, while one that was never measured is in `unansweredQueries`.

item.answers[].brands[].differentiation — object

Field	Type	Description
`axis`	`string`	The axis the model framed this brand as competing on. Values: `technology`, `price`, `service`, `speed`, `scale`.
`uniqueValue`	`string`	What the model said sets this brand apart, in its own words. The model’s claim, not a verified fact.

item.answers[].brands[].messaging — object

Field	Type	Description
`keywords`	`array<string>`	Keywords the model associated with this brand (up to 5).
`credibilitySignals`	`array<string>`	Claims the model offered as evidence for this brand — certifications, customer counts, awards. The model asserts these; it does not source them and CompetLab does not verify them.
`differentiationClaims`	`array<string>`	Differentiation claims the model attributed to this brand (up to 3). The model’s claims about the brand, not verified facts.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id`	Bad request — the payload failed validation.
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.
404	`check_not_found`	No `check` matches the id in the path.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "invalid_parameters",
    "message": "Domain is required",
    "status": 400
  }
}

Get AI visibility trend data

GET/v1/projects/{projectId}/ai-visibility/trend

Get AI visibility trend data over time for chart visualization. Returns time-series data points with customer and top competitor mention rates and AI Visibility Scores. Optionally filter by date range or specific AI provider — the provider filter applies to mention rates only; the AI Visibility Score is a single weighted composite across all providers, so customerAiScore/topCompetitorAiScore are null when a provider filter is applied. Every point comes from a scored check; under the full-coverage gate a cycle that did not get an answer to every query it asked has no point at all and is reported separately in incompleteCycles, so a gap in the series is distinguishable from a period when nothing was scheduled. Checks published before that gate stay plotted and can have been scored over fewer answers than they asked queries, and no point reports how many answers it counted. Returns up to 200 data points — use dateFrom/dateTo to narrow the range for longer histories.

Returns · { items, incompleteCycles }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`dateFrom`	`string`	Start date for trend data (ISO-8601)
`dateTo`	`string`	End date for trend data (ISO-8601)
`provider`	`string`	Filter by AI provider. Omit to get aggregated trend across all providers. Values: `openai`, `claude`, `gemini`.

Request


curl "https://api.competlab.com/v1/projects/507f1f77bcf86cd799439011/ai-visibility/trend?dateFrom=2026-01-01&dateTo=2026-03-15&provider=openai" \
  -H "CL-API-Key: YOUR_COMPETLAB_API_KEY"

Response 200 OK

Example


{
  "items": [
    {
      "date": "2026-03-15T10:00:00.000Z",
      "customerMentionRate": 66.7,
      "topCompetitorMentionRate": 88.9,
      "topCompetitorDomain": "competitor.com",
      "gap": -22.2,
      "customerAiScore": 73,
      "topCompetitorAiScore": 85
    }
  ],
  "incompleteCycles": [
    {
      "date": "2026-03-14T02:00:00.000Z",
      "reason": "incomplete_coverage",
      "measuredAnswers": 8,
      "expectedAnswers": 9
    }
  ]
}

Fields

items[] — each entry

Field	Type	Description
`date`	`string`	Data point date (ISO-8601)
`customerMentionRate`	`number \| null`	Customer mention rate percentage (0-100), or null when this point has no denominator to divide by: a check recorded before we stored its answer count, or — under a provider filter — a provider whose every slot on that check was unmeasured. A `0` means the models answered and named nobody; a null means there was nothing to compute a rate from. Plot a null as a break in the line, never as a zero. Nullable.
`topCompetitorMentionRate`	`number \| null`	Top competitor mention rate percentage (0-100), or null when this check found no top competitor, or when there is no denominator (see `customerMentionRate`). `topCompetitorDomain` is null on the same points. A forced `0` here used to draw the market leader flat along the bottom of the chart and the customer ahead of everyone. Nullable.
`topCompetitorDomain`	`string \| null`	Top competitor domain at this data point. Nullable.
`gap`	`number \| null`	Gap between customer and top competitor (negative means customer is behind), or null when this check had no top competitor to compare against — `topCompetitorDomain` is null on the same points. A `0` means genuinely level; a null means there was nobody to be level with. Plot a null as a break in the line, never as a point at zero. Nullable.
`customerAiScore`	`number \| null`	Customer AI Visibility Score (0-100). A single weighted composite across all providers — null when a provider filter is applied, since no per-provider score exists. Nullable.
`topCompetitorAiScore`	`number \| null`	Top competitor AI Visibility Score (0-100). A single weighted composite across all providers — null when a provider filter is applied, since no per-provider score exists. Nullable.

incompleteCycles[] — each entry

Field	Type	Description
`date`	`string`	When the cycle started (ISO-8601). It has no completion time to report.
`reason`	`string`	Why this cycle produced no point. `incomplete_coverage` — we did not end up with a usable answer for every query it asked. Absent on cycles recorded before this was stored; absence means the reason was not recorded, never that there wasn’t one. Values: `incomplete_coverage`.
`measuredAnswers`	`number \| null`	Answers that came back usable in this cycle, or null on a cycle that predates the recorded query count. Not a visibility figure — a cycle can be fully covered and score zero. Nullable.
`expectedAnswers`	`number \| null`	Answers the cycle asked for: 3 AI providers x the project’s prompt count at the time. The shortfall (expectedAnswers - measuredAnswers) is what did not arrive. Null on a cycle that predates the recorded query count — say the cycle did not complete and give no numbers. Never treat a null as 0: the subtraction would report no shortfall on a cycle that measurably failed. This endpoint is where cycles are enumerated for plotting, so it is where that subtraction is most likely to run. Nullable.

Errors

Status	Code	Meaning
401	`api_key_missing` · `api_key_invalid` · `api_key_revoked` · `api_key_expired` · `insufficient_scope`	The `CL-API-Key` is missing, malformed, revoked, expired, or lacks the required scope.

Every error uses the shared { error: { code, message, status } } envelope; code is one of the values listed above.


{
  "error": {
    "code": "api_key_invalid",
    "message": "Invalid API key",
    "status": 401
  }
}