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 for a project: the market map — which companies the AI models recommend in this category, ordered by how often each is named, and where you stand among them — then AI Visibility Scores, mention rates and per-model breakdowns for every company found. 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. Each check asks every prompt in the project against every AI model it was dispatched to — 5 today, but a check keeps the model set it ran with, so read answerCoverage.queriesSent and providerStatus for that check’s own count rather than assuming today’s. 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 were read for every query they asked — a usable answer came back, or the model was read and had none to show (noAnswerShown, the third query state beside answers and unansweredQueries: read, nothing shown, excluded from every count, not a failure); 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 not scored, 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=. It is large, and how large depends on the project. An entry is one brand a model named, at about 1,500 characters each — so the block grows with three things at once: how many prompts the project asks — 8 on every plan and in the trial — times five models, how many models answered, and how many companies each answer named. No figure quoted here can stand in for summary.totalEntries; read it and size the fetch from it. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which totalEntries does not predict and which brand= keeps by design. 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, and how large depends on the project. An entry is one brand a model named, at about 1,500 characters each — so the block grows with three things at once: how many prompts the project asks — 8 on every plan and in the trial — times five models, how many models answered, and how many companies each answer named. No figure quoted here can stand in for `summary.totalEntries`; read it and size the fetch from it. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which `totalEntries` does not predict and which the `brand=` filter keeps by design. 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`, `perplexity`, `google_ai_overviews`.
`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: it keeps at most one brand entry per answer instead of every brand the model named, and none at all on the answers that did not name it. Compare `summary.totalEntries` with the answer count to see the saving on this check. Google AI Overviews answers still carry their overview text and cited pages, which this filter keeps by design.
`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.
`view`	`string`	How much of the response to return. `compact`: `summary.marketMap.brands` is one page of rows — the core by default — with `summary.marketMap.brandsPage` saying where it sits; the customer’s own row and every tracked competitor’s are always included. Every other field is unchanged, and `untrackedCoreBrands` and `customerStanding` are still read from the whole map. `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`. Values: `compact`, `full`.
`mapOffset`	`number`	Rows of `summary.marketMap.brands` to skip, in the order the list is stored. Default 0. Pages the compact view: sent without `view` it selects the compact view, and beside `view=full` it is refused with `paging_requires_compact_view`. Min `0`.
`mapLimit`	`number`	Rows of `summary.marketMap.brands` to return, 1 to 200. Default the core size (`summary.marketMap.coreSize`), and never fewer than 10. Pages the compact view: sent without `view` it selects the compact view, and beside `view=full` it is refused with `paging_requires_compact_view`. Range `1`–`200`.

Request


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

Response 200 OK

Example


{
  "item": {
    "readingGuide": {
      "summary.pages": "Pages the engines RETRIEVED while answering, never pages they cited."
    },
    "lastUpdatedAt": "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": [
          {
            "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
      },
      "mentionRateGap": -22.2,
      "totalCompetitorsFound": 8,
      "totalQueries": 12,
      "totalEntries": 45,
      "competitorRankings": [
        {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "isOwn": false,
          "mentionCount": 7,
          "mentionRate": 77.8,
          "aiScore": 68,
          "isTracked": false
        }
      ],
      "promptMarket": {
        "state": "rivals_named_in_most_answers",
        "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",
            "state": "answers_and_rival_list_disagree",
            "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
          }
        ]
      },
      "marketMap": {
        "checksAnalysed": 5,
        "answersReceived": 60,
        "tailIsProvable": true,
        "coreSize": 9,
        "perEngine": {
          "openai": {
            "answersReceived": 15
          },
          "claude": {
            "answersReceived": 15
          },
          "gemini": {
            "answersReceived": 15
          },
          "perplexity": {
            "answersReceived": 15
          },
          "google_ai_overviews": {
            "answersReceived": 15
          }
        },
        "profileEngines": [
          "openai",
          "claude",
          "gemini",
          "perplexity"
        ],
        "brands": [
          {
            "answersNaming": 31,
            "answersReceived": 60,
            "presence": 52,
            "presenceLow": 40,
            "presenceHigh": 63,
            "zone": "named_in_a_quarter_or_more_of_answers",
            "domain": "sienge.com.br",
            "name": "Sienge",
            "isOwn": false,
            "rankByPresence": 2,
            "perEngine": {
              "openai": {},
              "claude": {},
              "gemini": {},
              "perplexity": {},
              "google_ai_overviews": {}
            },
            "endorsement": {
              "value": 64,
              "answersRead": 9,
              "low": 51,
              "high": 77
            },
            "pricePerception": {
              "value": 64,
              "answersRead": 9,
              "low": 51,
              "high": 77,
              "tier": "mid_range",
              "tierAnswers": 6
            }
          }
        ],
        "brandsPage": {
          "offset": 0,
          "limit": 10,
          "total": 96,
          "hasMore": true
        }
      }
    },
    "untrackedCoreBrands": [
      {
        "domain": "sienge.com.br",
        "name": "Sienge",
        "presence": 52,
        "presenceLow": 40,
        "presenceHigh": 63,
        "answersNaming": 31,
        "answersReceived": 60
      }
    ],
    "customerStanding": {
      "endorsement": {
        "explanation": {
          "code": "described_less_warmly_than_some_core_companies",
          "text": "Of the 7 core companies with enough answers to compare, the AI models describe you less warmly than 3; the evidence cannot yet separate you from the other 4."
        },
        "answersRead": 8,
        "coreCompared": 7,
        "coreAboveYou": 3,
        "coreBelowYou": 0,
        "coreNotSeparable": 4,
        "state": "described_less_warmly_than_some_core_companies"
      },
      "price": {
        "explanation": {
          "code": "described_less_warmly_than_some_core_companies",
          "text": "Of the 7 core companies with enough answers to compare, the AI models describe you less warmly than 3; the evidence cannot yet separate you from the other 4."
        },
        "answersRead": 8,
        "coreCompared": 7,
        "coreAboveYou": 3,
        "coreBelowYou": 0,
        "coreNotSeparable": 4,
        "state": "read_as_cheaper_than_every_core_company"
      }
    },
    "latestCheckDataAvailable": {
      "available": false,
      "reason": "incomplete_coverage",
      "measuredAnswers": 8,
      "expectedAnswers": 12,
      "absentAnswers": 1
    },
    "answers": [
      {
        "provider": "openai",
        "promptIndex": 0,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "answerText": "For mid-market sales teams, forecasting platforms such as Competitor Inc, Rival Software and Example Analytics combine CRM data with AI-driven projections.",
        "askedIn": {
          "locationName": "United States",
          "languageName": "English"
        },
        "sources": [
          {
            "url": "https://www.g2.com/categories/sales-forecasting",
            "domain": "g2.com",
            "title": "Best Sales Forecasting Software"
          }
        ],
        "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"
      }
    ],
    "noAnswerShown": [
      {
        "provider": "google_ai_overviews",
        "promptIndex": 1,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "reason": "no_ai_overview_shown"
      }
    ],
    "providerStatus": {
      "openai": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "claude": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "gemini": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "perplexity": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "google_ai_overviews": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      }
    },
    "answerCoverage": {
      "queriesSent": 12,
      "answersCounted": 8
    },
    "answersTruncated": false
  }
}

Fields

item — object

Field	Type	Description
`readingGuide`	`object`	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.
`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`.
`untrackedCoreBrands`	`array<object>`	Companies the AI models place in the core of the customer’s market that the project does NOT track — the highest-value line this dimension produces. Every other dimension benchmarks against the competitor list, so a core brand missing from it is a hole in the whole account, found here. Resolved against the project’s CURRENT competitor list. ABSENT when `summary.promptMarket` is not `rivals_named_in_most_answers` or could not be produced — a recommendation drawn from a map that may describe the wrong market is withheld, and absence never means ‘none’. An EMPTY list means the gate is healthy and every core brand is already tracked, which is a real finding. Report it as a recommendation to add these companies, never as a fact about them. See `item.untrackedCoreBrands[]`.
`customerStanding`	`object`	The customer’s own standing against the core of this market on the two profile readings — how warmly the models describe them, and where the models place their price — each as a state token and a sentence to report verbatim. Derived from `summary.marketMap` by one shared rule, so the app and this API cannot say different things. A reading of the map, not a recommendation: present whenever a published map is, and read under `summary.promptMarket` exactly as the map is — unless that state is `rivals_named_in_most_answers`, say the market it compares against may not be the customer’s. Each reading inside is absent on its own evidence floor, and absence never means ‘level’. Never derive a gap, a distance or a rank from these; never set `endorsement` against `presence`. See `item.customerStanding`.
`latestCheckDataAvailable`	`object`	Present ONLY when the project’s most recent check was not scored: at least one query it asked came back without a usable answer. A query the model was read for and had no answer to show does not count against coverage. When present, every other field in this response comes from an EARLIER check, and `lastUpdatedAt` is older than the most recent check attempted: report those fields as of that date. Absent when the most recent check published normally, and absent when a later check has since published. Never phrase the shortfall as a fraction — this dimension’s own metric is an n-of-N over the same denominator, so a fraction reads as a visibility rate. 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` and `noAnswerShown`. `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` and `noAnswerShown` 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. Per-brand prose — description, ranking rationale, audience, pricing tier, messaging, differentiation — is present only for models that describe brands; a brand row carrying only `rank`, `name` and `domain` means Google AI Overviews named it in prose, and the prose is on that answer’s `answerText`. ATTRIBUTION: every piece of prose in this block — descriptions, ranking rationales, audiences, claims, and the overview text itself — 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 was read — answered, or listed under `noAnswerShown` — which is the normal case, because a check is only scored when every query it asked was read. 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 and `noAnswerShown.length` recovers the queries sent — but a shortfall written as a fraction, 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[]`.
`noAnswerShown`	`array<object>`	Queries the model was read for and had no answer to show — today, prompts for which Google’s results page carried no AI Overview. Not a failure and not an answer: these slots are excluded from every count on this payload. Separate from `unansweredQueries`, which are queries we could not measure. Present ONLY when `includeAnswers=true`. Narrowed by `provider` and `promptIndex`, never by `brand`. An empty array means every query the check sent was either answered or could not be measured. See `item.noAnswerShown[]`.
`providerStatus`	`object`	Per-model reporting status for this check: which of the models this check asked returned data, when, and how much. One entry per model the check ASKED — a model is absent when the check did not ask it, because checks keep the model set they were run with; absent means not measured, never ‘did not report’. Present ONLY when `includeAnswers=true`. It carries no visibility judgement, and it is NOT narrowed by the filters — it always describes every model the check asked 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 — both read from the check’s own record of its ask, never inferred from the length of `answers`. Present ONLY when `includeAnswers=true`. 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 answers were dropped from the end of `answers`. The cut lands on a WHOLE PROMPT ROUND, never inside one: `answers` is ordered prompt by prompt across the models, so truncation drops the highest `promptIndex` values and no model is ever removed by truncation from a prompt that is still present — group the array by `promptIndex` and no round is short. A model missing from a prompt that IS present is in `unansweredQueries` or `noAnswerShown`, not cut; neither of those arrays is ever truncated, so a prompt absent from `answers` is not a prompt no model answered. Individual `brands` lists are never partially truncated. `summary`, `providerStatus` and `answerCoverage` are never affected. Narrow the response with `provider` or `promptIndex` to get a complete view — `brand` keeps every answer, and each Google AI Overviews answer’s overview text and cited pages with it, so it shrinks the payload far less. 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`	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 it is the ask — every AI model the check asked × every prompt it ran — minus the queries a model was read for and had no answer to show (`noAnswerShown`); 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.
`totalEntries`	`number`	Total brand entries across this check’s counted answers — one per brand a model named, summed over every answer. This is the size preview for `includeAnswers=true`: an entry serializes to about 1,500 characters. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which this count does not predict and which the `brand=` filter keeps by design.
`competitorRankings`	`array<object>`	Every brand this check’s counted answers named, plus the customer’s own row, in the ORDER TO RENDER: `mentionRate` desc, then `aiScore` desc, then domain. One check’s view; the windowed view with its uncertainty is `marketMap`. Nothing here is positional, so never re-sort or compare rows by position. See `item.summary.competitorRankings[]`.
`promptMarket`	`object`	Whether this project’s prompts are reaching the market its tracked competitor list describes — a reading about the QUESTIONS we ask, not about the brand’s visibility. Every other number in this summary is arithmetic over those prompts, so this is the field that says whether they are measuring the right market at all. ABSENT means no reading could be produced: the account tracks no competitors to test the prompts against, or no answer came back to test them with. There is deliberately no token for that case, so absence is the only way it is expressed — and absence NEVER means the prompts are fine. Do not report a missing `promptMarket` as a pass, and do not infer one from the numbers beside it. This reading suppresses nothing: everything else in this summary is complete and published whatever it says, because a customer may have chosen unusual prompts deliberately and their data is the only evidence they can judge that on. See `item.summary.promptMarket`.
`marketMap`	`object`	THE MARKET MAP — which companies the AI models recommend in this project’s category, how often each is named over the last few checks, where the customer sits among them, and which of those companies the project is not tracking. Lead with it: ‘Nine companies make up this market as the AI models draw it; the customer is one of them, 7th of 9 by how often it is named.’ Every share is a share of answers analysed with its range beside it; two brands whose ranges overlap are not ordered. Read `promptMarket` first: if it is not `rivals_named_in_most_answers`, say the prompts may not describe this project’s market and that the map below cannot be trusted — a confident map of the wrong market is the worst output this product can produce. Not returned on history rows; see the dashboard or a check’s detail. See `item.summary.marketMap`.

item.untrackedCoreBrands[] — each entry

Field	Type	Description
`domain`	`string`	Brand domain.
`name`	`string`	Brand name.
`presence`	`number`	Share of answers naming it — see `marketMap.brands[].presence`.
`presenceLow`	`number`	Lower bound of the range.
`presenceHigh`	`number`	Upper bound of the range.
`answersNaming`	`number`	Answers naming it.
`answersReceived`	`number`	Answers analysed.

item.customerStanding — object

Field	Type	Description
`endorsement`	`object`	How warmly the models describe the customer against the core of this market. ABSENT when fewer than 3 core companies carry a settled endorsement reading, or the customer’s row carries none — a comparison needs both sides, and absence never means ‘level’. The sentence counts the core companies it could compare against, which can be fewer than marketMap.coreSize: a core company described in too few answers is left out, and the customer is never counted among them. See `item.customerStanding.endorsement`.
`price`	`object`	Where the models place the customer’s price against the core of this market. ABSENT when fewer than 3 core companies carry a settled price reading, or the customer’s row carries none. Its count of core companies follows the same rule as the endorsement standing’s and can differ from marketMap.coreSize. See `item.customerStanding.price`.

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` — at least one query it asked could not be read — no usable answer came back from it. A query the model was read for and had no answer to show does not count against coverage. Values: `incomplete_coverage`.
`measuredAnswers`	`number`	Answers that did come back usable in that check. NOT a visibility figure — a check can be fully covered and still score zero.
`expectedAnswers`	`number`	Answers that check asked for: every AI model it queried, against every prompt it ran — read the number from this field; do not recompute it from today’s model count, which is not necessarily that check’s. `expectedAnswers` − `measuredAnswers` is the uncounted total, and it is two facts added together: queries that could not be read, plus queries the model was read for that had no answer to show (`absentAnswers`). Subtract `absentAnswers` from that shortfall to get the number of queries that could not be read; report the two apart, never the total as answers that failed to arrive.
`absentAnswers`	`number`	Queries in that check the model was read for and had no answer to show — today, prompts for which Google’s results page carried no AI Overview. They sit inside `expectedAnswers` − `measuredAnswers` without being failures: that shortfall minus this figure is the number of queries that could not be read.

item.answers[] — each entry

Field	Type	Description
`provider`	`string`	Which AI produced this answer. Values: `openai`, `claude`, `gemini`, `perplexity`, `google_ai_overviews`.
`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.
`answerText`	`string`	The answer as the model wrote it. Present for Google AI Overviews: the overview text, verbatim, from which the brands below were read in order of first mention. Absent for models that answer in a ranked list. Model prose, attributed to the model that wrote it.
`askedIn`	`object`	The Google market the question was asked in. Google AI Overviews only. See `item.answers[].askedIn`.
`sources`	`array<object>`	The pages cited beside this answer. Google AI Overviews only — the pages Google cited with the overview, distinct by URL, up to 20. ABSENT means either that Google listed no citations or that every one it listed was a masked redirect we could not resolve to a page — never that Google cited nothing. An EMPTY array is the measured ‘it cited nothing’. Absent for every other model. See `item.answers[].sources[]`.
`brands`	`array<object>`	Brands this model named, in the order it ranked them — for Google AI Overviews, in the order of first mention in `answerText`, each carrying only `name` and `domain`. Every answer in this array arrived — a query that produced nothing is not here at all, it is in `unansweredQueries`, and a query the model was read for and had no answer to show is in `noAnswerShown`. 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`, `perplexity`, `google_ai_overviews`.
`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 model 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.noAnswerShown[] — each entry

Field	Type	Description
`provider`	`string`	Which AI this query was sent to — we reached it and it had no answer to show. Values: `openai`, `claude`, `gemini`, `perplexity`, `google_ai_overviews`.
`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_ai_overview_shown` — Google’s results page for this prompt carried no AI Overview. A measured fact about the prompt on Google that day: not a failure, not an answer, and nothing the customer’s prompt did wrong. Report it as ‘Google showed no AI Overview for this question — not counted’; NEVER as ‘not mentioned’, ‘0 mentions’, or a query that failed. This query is excluded from every count and rate on this response. Values: `no_ai_overview_shown`.

item.providerStatus — object

Field	Type	Description
`openai`	`object`	ChatGPT. See `item.providerStatus.openai`.
`claude`	`object`	Claude. See `item.providerStatus.claude`.
`gemini`	`object`	Gemini. See `item.providerStatus.gemini`.
`perplexity`	`object`	Perplexity. See `item.providerStatus.perplexity`.
`google_ai_overviews`	`object`	Google AI Overviews. See `item.providerStatus.google_ai_overviews`.

item.answerCoverage — object

Field	Type	Description
`queriesSent`	`number`	Queries this check sent: every AI model it queried, against every prompt it ran — read the number from this field; do not recompute it from today’s model count, which is not necessarily that check’s. Checks keep the model set and the prompt count they were run with.
`answersCounted`	`number`	Queries that came back with an answer we could use. The shortfall is `queriesSent` − `answersCounted`, and it is two different facts added together: `queriesSent` − `answersCounted` = `unansweredQueries.length` + `noAnswerShown.length` — queries we could not measure, plus queries the model was read for and had no answer to show. On a check published under the full-coverage gate the whole shortfall is in `noAnswerShown`; on older checks it can exceed both arrays together, because a model that failed before answering anything recorded no query slots to list. Trust the shortfall, not the array lengths. NEVER present these numbers as a fraction: this dimension’s headline metric is already an n-of-N over the same denominator, so any shortfall written as a fraction gets read as a visibility rate. State them as separate facts that cannot be divided by each other — “We sent every query we planned; Google showed no AI Overview for one of them, so it is not counted”, or, for a query that could not be read, “one 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`	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 number. Under the full-coverage gate (a check publishes only once every query it asked was read) that is the ask — every AI model the check asked × its recorded prompt count — MINUS the queries a model was read for and had no answer to show (`noAnswerShown`); 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’. A `0` is a real rate: none of the answers this check counted named this brand.
`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`	AI Visibility Score, 0-100. 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. Averaged over the answers this check counted and smoothed over up to the last 5 published checks. Present on every published check, and a `0` is a measured score — never ‘unscored’. 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 it to tell that case from a brand no counted answer named.
`perProvider`	`object`	Per-model breakdown, one entry per AI model this check asked. A model is ABSENT when the check did not ask it — checks keep the model set they were run with, so a check from before a model was added carries no entry for it. Absent means not measured; never read it as ‘not mentioned’. A model that is PRESENT with `mentioned: false` is read together with its `answersCounted`: beside a non-zero count it answered and did not name the customer, beside `answersCounted: 0` it was read and had no answer to show on every prompt, which is not a measurement of the customer at all. 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. One row per prompt the check asked, so the array length is that check’s own prompt count. 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`	Top competitor mention rate percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent.

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
`mentionCount`	`number`	Total mentions across the answers this check counted.
`mentionRate`	`number`	Mention rate as percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. This row names a THIRD PARTY: a `0` here is a measured rate — none of the answers this check counted named them — and must be reported as exactly that.
`aiScore`	`number`	AI Visibility Score (0-100), on the same rule as `customer.aiScore`. 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. This row names a THIRD PARTY, so the reading matters more here than anywhere else on the response. 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. Reporting a `0` as ‘never named’ is a false claim about another company published under our name. 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.
`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.summary.promptMarket — object

Field	Type	Description
`state`	`string`	Which of the three readings this evidence supports. `rivals_named_in_most_answers` — most of the answers named at least one company the account tracks, so the numbers beside this are measuring the intended competition. `rival_match_too_close_to_call` — some answers named a tracked competitor and some named none, in a proportion this much evidence cannot separate; an undecided reading, not a milder version of the next one. `answers_and_rival_list_disagree` — almost none of the answers named a tracked competitor. That last one does NOT assert that the prompts are wrong. It compares two things the customer supplied, the prompts and the tracked competitor list, so a disagreement means one of them does not match what the models said and this comparison cannot tell you which. A narrow market that genuinely does not come up in AI answers yet produces the same reading, and that is a real finding rather than a defect. Report the disjunction, and point at the stored answers (`includeAnswers=true`) — they are the evidence that settles it. Values: `rivals_named_in_most_answers`, `rival_match_too_close_to_call`, `answers_and_rival_list_disagree`.
`explanation`	`object`	The sentence to report for this reading, with a stable code beside it. This is payload rather than documentation: it is the only place the reading is expressed in words, and the app, this API and the MCP tools all say these same words. Render `text` verbatim. See `item.summary.promptMarket.explanation`.
`answersNamingAnyRival`	`number`	How many of the answers behind this reading named at least one company the account tracks. Membership, not volume: an answer that named four tracked competitors counts once, exactly like an answer that named one. It says NOTHING about the customer’s own visibility — a window in which every answer named a rival and none named the customer reads healthy here and 0% under `customer.mentionRate`. Never present it as a mention rate, and never pair it with `totalQueries`, which counts a different set over a different window.
`answersMatchingCurrentPromptText`	`number`	Divide `answersNamingAnyRival` by THIS figure and nothing else. It is the universe that numerator is drawn from: answers across this reading’s window of checks that were produced by the account’s prompts as their text stands TODAY. Two exclusions. A query that produced no usable answer is out entirely and is never counted as an answer that named nobody. An answer produced before the customer last edited a prompt is also out, because it answers a question nobody is asking any more. THIS RESPONSE CARRIES A SECOND ANSWER COUNT drawn from the same window — `marketMap.answersReceived`, which pools every usable answer whatever wording produced it, and is the divisor for brand presence. This figure is never larger than that one and is EQUAL to it whenever no prompt has been reworded inside the window, which is the steady state; seeing the two agree does not mean they are the same field. A difference means a prompt’s text changed inside the window, and the size of the difference is how many answers that edit orphaned. Also unrelated to `totalQueries` above, which counts ONE check’s answers while this counts a window of them.
`checksAnalysed`	`number`	How many published checks this reading was drawn from. Checks, never days — checks are not daily, and the interval is a schedule setting. Quote it whenever you quote the reading: a low number is the usual reason a reading comes back `rival_match_too_close_to_call`, and that state describes thin evidence rather than weak prompts. Counts the checks that contributed an answer on today’s prompt text, so it can sit BELOW `marketMap.checksAnalysed`, which counts every check that contributed any usable answer. The two are drawn from one window and agree unless a prompt was reworded inside it.
`perPrompt`	`array<object>`	One reading per prompt, each with its own `state` — every prompt this reading could attribute answers to appears here, whether it is reaching the tracked competitor list, failing to, or not yet separable. Read each entry’s `state` and report its `explanation.text` verbatim: do NOT treat membership of this list as a fault, because the healthy and the undecided readings are in it too. A prompt is MISSING for exactly one reason — no answer in the window was produced by its current wording, which is what happens for a while after the customer edits it — so absence means ‘no evidence for this prompt yet’ and never a verdict. An empty array means that was true of every prompt; the array being absent means it was true of the check as a whole. An undecided entry still carries its counts, and those counts are evidence of how thin the sample is, never a position: three answers cannot rank one prompt against another, and presenting a partial share as a score is the error this state exists to prevent. Note that entries make a history row several times larger and appear on every project, so a page of history may hit the response size cap sooner — lower `limit` if `truncated` comes back true. See `item.summary.promptMarket.perPrompt[]`.

item.summary.marketMap — object

Field	Type	Description
`checksAnalysed`	`number`	Published checks pooled into this map — this check plus up to the previous 4. Checks, never days: the interval is a schedule setting, and a three-day and a monthly project showing the same `answersReceived` are looking at equally trustworthy maps.
`answersReceived`	`number`	Usable answers pooled across those checks and every AI model — the total every pooled `presence` on `brands` divides by. Quote it whenever you quote a share. This counts EVERY usable answer in the window, whatever prompt wording produced it, which is what a market picture needs: an answer naming a rival is evidence about the market even if the question that drew it has since been reworded. `promptMarket.answersMatchingCurrentPromptText` counts the narrower set produced by today’s wording over the same window, so it is never larger than this and is equal whenever no prompt has been reworded — the two agreeing is the steady state, not a sign they are one field. Divide a brand’s `answersNaming` by THIS figure and nothing else.
`tailIsProvable`	`boolean`	Whether the sample is large enough for ANY brand to reach `named_in_under_a_tenth_of_answers` — the upper bound of a brand named in exactly one answer falls below 10% — 56 answers with the interval used, on the rounded bounds this response carries. While false no brand is in that zone, and the honest sentence is ‘no brand can be ruled out of this market yet’ — never ‘tail’, never ‘irrelevant’.
`coreSize`	`number`	Brands in `named_in_a_quarter_or_more_of_answers` — the size of the market as the models draw it. Lead with it: ‘Nine companies make up this market as the AI models draw it.‘
`perEngine`	`object`	Usable answers per AI model in the window. A model absent here returned no usable answer in the window. See `item.summary.marketMap.perEngine`.
`profileEngines`	`array<string>`	The AI models the `endorsement` and `pricePerception` readings on `brands` were read from — those with at least one usable answer in the window that described a company. A model that names companies without describing them (Google AI Overviews) is never here, and a model that returned no usable answer in the window is not here either. Name them whenever you quote a reading. Empty means no answer in the window described anybody, and every reading on `brands` is `null`.
`brands`	`array<object>`	Every brand any answer in the window named, plus the customer’s own row, in the ORDER TO RENDER: `presence` desc, then domain. Never re-sort it by anything positional — there is nothing positional to sort by, by design. Read `isOwn` to find the customer; `rankByPresence` says where they sit and shares its value across ties, and is null on a row named in no answer. See `item.summary.marketMap.brands[]`.
`brandsPage`	`object`	Compact view only: which rows of the map `brands` carries — the stored order, from `offset`, `limit` rows, plus the customer’s own row and every tracked competitor’s whenever they fall outside them. `total` is every row on the map. Page on with `mapOffset` and `mapLimit`; `coreSize`, `untrackedCoreBrands` and `customerStanding` always describe the whole map, whatever page this is. See `item.summary.marketMap.brandsPage`.

item.customerStanding.endorsement — object

Field	Type	Description
`explanation`	`object`	See `item.customerStanding.endorsement.explanation`.
`answersRead`	`number`	Answers in the window that carried this reading for the customer.
`coreCompared`	`number`	Core companies with a settled reading and an interval the customer’s was set against — at least 3 whenever a comparison was made, and 0 in the too-few state, where nothing was compared. The three counts below sum to it.
`coreAboveYou`	`number`	Core companies whose whole interval sits ABOVE the customer’s — the customer is separably below each of them.
`coreBelowYou`	`number`	Core companies whose whole interval sits BELOW the customer’s.
`coreNotSeparable`	`number`	Core companies whose interval overlaps the customer’s — no order between them and the customer may be stated. Usually most of the core: the customer is usually the least-described brand on their own map and so carries the widest interval.
`state`	`string`	`state` names a measured condition about the customer’s OWN row against the companies at the core of this market (`named_in_a_quarter_or_more_of_answers`, never the customer), on this one reading — like against like, never a reading against a share of answers — and it says ONLY what the intervals separate: a core company counts as above the customer only when its whole interval sits above the customer’s, below only when wholly below, and the rest are not separable. `explanation.text` is the sentence to report, VERBATIM: never paraphrase it and never build a claim of your own from the token or the counts. `answersRead` is how many answers the customer’s reading rests on; `coreCompared` how many core companies carried an interval to compare against, split into `coreAboveYou`, `coreBelowYou` and `coreNotSeparable`; quote them as the sentence does. `too_few_answers_described_you` means fewer than 6 answers carried a reading for the customer, and the figure on their row is a label that will move when an answer leaves the window — not a comparison. Values: `described_less_warmly_than_every_core_company`, `described_less_warmly_than_some_core_companies`, `not_separable_from_the_core`, `described_more_warmly_than_some_core_companies`, `described_more_warmly_than_every_core_company`, `described_between_core_companies`, `too_few_answers_described_you`.

item.customerStanding.price — object

Field	Type	Description
`explanation`	`object`	See `item.customerStanding.price.explanation`.
`answersRead`	`number`	Answers in the window that carried this reading for the customer.
`coreCompared`	`number`	Core companies with a settled reading and an interval the customer’s was set against — at least 3 whenever a comparison was made, and 0 in the too-few state, where nothing was compared. The three counts below sum to it.
`coreAboveYou`	`number`	Core companies whose whole interval sits ABOVE the customer’s — the customer is separably below each of them.
`coreBelowYou`	`number`	Core companies whose whole interval sits BELOW the customer’s.
`coreNotSeparable`	`number`	Core companies whose interval overlaps the customer’s — no order between them and the customer may be stated. Usually most of the core: the customer is usually the least-described brand on their own map and so carries the widest interval.
`state`	`string`	`state` names a measured condition about the customer’s OWN row against the companies at the core of this market (`named_in_a_quarter_or_more_of_answers`, never the customer), on this one reading — like against like, never a reading against a share of answers — and it says ONLY what the intervals separate: a core company counts as above the customer only when its whole interval sits above the customer’s, below only when wholly below, and the rest are not separable. `explanation.text` is the sentence to report, VERBATIM: never paraphrase it and never build a claim of your own from the token or the counts. `answersRead` is how many answers the customer’s reading rests on; `coreCompared` how many core companies carried an interval to compare against, split into `coreAboveYou`, `coreBelowYou` and `coreNotSeparable`; quote them as the sentence does. ‘Read’ is deliberate throughout: this is the tier the models think the customer charges, never what the customer charges. `too_few_answers_stated_your_price` means fewer than 6 answers stated a tier for the customer. Values: `read_as_cheaper_than_every_core_company`, `read_as_cheaper_than_some_core_companies`, `price_not_separable_from_the_core`, `read_as_pricier_than_some_core_companies`, `read_as_pricier_than_every_core_company`, `read_as_priced_between_core_companies`, `too_few_answers_stated_your_price`.

item.answers[].askedIn — object

Field	Type	Description
`locationName`	`string`	The country or region the question was asked from, as Google names its markets.
`languageName`	`string`	The language the question was asked in, as Google names it.

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

Field	Type	Description
`url`	`string`	Address of the cited page.
`domain`	`string`	Domain of the cited page — the site Google cited.
`title`	`string`	Title of the cited page, as Google displayed it.

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

Field	Type	Description
`rank`	`number`	Position in this model’s answer — 1 means named first. For models that answer with a ranked list, this is the rank they gave. For Google AI Overviews, which answers in prose, it is the ORDER OF FIRST MENTION in `answerText`, computed by CompetLab — Google assigned no position, so never report it as a rank Google gave. 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`sentiment`	`string`	How warmly the model spoke about this brand in this answer. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. Values: `highly_recommended`, `recommended`, `mentioned`, `alternative`.
`mentionContext`	`string`	The role this brand played in the answer. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. Values: `direct_recommendation`, `comparison`, `alternative`, `niche_fit`.
`targetAudience`	`string`	Who the model said this brand is for. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`pricingSignal`	`string`	The price tier the model placed this brand in. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`features`	`array<string>`	Features the model highlighted for this brand (max 5). Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`differentiation`	`object`	How the model framed this brand’s differentiation. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. See `item.answers[].brands[].differentiation`.
`messaging`	`object`	The messaging the model associated with this brand. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.perplexity — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.google_ai_overviews — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — 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`	ChatGPT metrics. Nested — see the Example tab.
`claude`	`object`	Claude metrics. Nested — see the Example tab.
`gemini`	`object`	Gemini metrics. Nested — see the Example tab.
`perplexity`	`object`	Perplexity metrics. Nested — see the Example tab.
`google_ai_overviews`	`object`	Google AI Overviews 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 where the model answered, but a model with `answersCounted: 0` under `perProvider` was read and had no answer to show on this check, and on a check published before that gate it could be an answer that never arrived.
`score`	`number`	0-100 position score for this prompt, averaged over the models whose answers this check counted — never over a fixed model count. Higher is better. 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. So it is not a rank and not a percentage of anything. 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. `mentionedBy` separates the two: non-empty means the models named them here. 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.summary.promptMarket.explanation — object

Field	Type	Description
`code`	`string`	Stable identifier for this sentence. Branch on it if you need to; never substitute your own wording for it. The project-level reading and a per-prompt reading carry DIFFERENT codes even where their `state` matches, so the two are not interchangeable and de-duplicating a list by code will not collapse them.
`text`	`string`	The sentence to report, in the words every CompetLab surface uses. Render it VERBATIM — do not paraphrase it, shorten it, or compose your own sentence from `state`. The wording is chosen to say only what this comparison can support, and a rewrite reliably says more than that. It carries no fraction and no percentage on purpose: this dimension’s headline metric is itself a count of answers, so a number inside this sentence gets read as a visibility rate. The counts are the sibling fields — put them beside the sentence, never inside it.

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

Field	Type	Description
`promptId`	`string`	Stable identifier for the prompt, minted once and kept for the life of that prompt — including when its wording is rewritten. It is the durable way to follow one prompt across checks. Note that the project endpoint returns prompt TEXTS and no ids, so lining a row up with a project’s current prompts means matching on `promptTextInProject` below.
`promptTextInProject`	`string`	The prompt’s wording as the project holds it now — which is also the wording every answer behind this reading was produced by, because answers produced by wording that has since been rewritten are excluded from it. Quote it so a reader can find the prompt in the project’s settings, and match on it to line this row up with the project endpoint’s prompt list. It will always match a current prompt; `promptId` is the durable handle if you need to follow one across edits.
`state`	`string`	This prompt’s own reading, on the same three-token scale as the project-level `state` and read in exactly the same way. Computed over the answers to THIS prompt alone, so it can differ from the project-level reading — which is the whole reason to look here. Values: `rivals_named_in_most_answers`, `rival_match_too_close_to_call`, `answers_and_rival_list_disagree`.
`explanation`	`object`	The sentence to report for this prompt, rendered verbatim like the project-level one. It is deliberately IDENTICAL for every prompt in the same state and never names the prompt — `promptId` and `promptTextInProject` do that. Say it once over a list of prompts rather than repeating a near-identical paragraph per row. Nested — see the Example tab.
`answersNamingAnyRival`	`number`	Answers to THIS prompt that named at least one company the account tracks. Membership, not volume: an answer that named four tracked competitors counts once, exactly like an answer that named one.
`answersMatchingCurrentPromptText`	`number`	Divide `answersNamingAnyRival` by THIS figure and nothing else. It is the universe that numerator is drawn from: answers to this prompt as its text stands TODAY. Two exclusions. A query that produced no usable answer is out entirely and is never counted as an answer that named nobody. An answer produced before the customer last edited this prompt’s text is also out, because it answers a question nobody is asking any more. Do not compare it to a figure on the market map: this row covers ONE prompt while the map pools every prompt, so it is a fraction of the map’s total by construction and that gap is not evidence of anything.

item.summary.marketMap.perEngine — object

Field	Type	Description
`openai`	`object`	ChatGPT coverage. Nested — see the Example tab.
`claude`	`object`	Claude coverage. Nested — see the Example tab.
`gemini`	`object`	Gemini coverage. Nested — see the Example tab.
`perplexity`	`object`	Perplexity coverage. Nested — see the Example tab.
`google_ai_overviews`	`object`	Google AI Overviews coverage. Nested — see the Example tab.

item.summary.marketMap.brands[] — each entry

Field	Type	Description
`answersNaming`	`number`	Answers in this view — the pooled map, or one AI model’s reading — that named the brand. Deduplicated within an answer — a brand named twice in one answer counts once — and matched on the domain, never on the brand’s wording.
`answersReceived`	`number`	The universe `answersNaming` is drawn from: usable answers in this view. Queries that produced no usable answer are out of it entirely. Quote it whenever you quote the share.
`presence`	`number`	`answersNaming / answersReceived × 100`, whole percent. THE ordering of every brand list here: how often a brand is named, never how high it sat. A share of answers analysed — never of queries sent, and never a probability. Always read with `presenceLow` / `presenceHigh` beside it.
`presenceLow`	`number`	Lower bound of a 95% interval on `presence`, in the same percent scale. Two brands whose ranges overlap are NOT ordered, whatever their rank says — never state that one is ahead of the other.
`presenceHigh`	`number`	Upper bound of the same interval. See `presenceLow`.
`zone`	`string`	Where this share sits once the sample’s uncertainty is taken into account. `named_in_a_quarter_or_more_of_answers`: the LOWER bound of the range is above 25% — these companies are the market as the AI models draw it. `named_in_under_a_tenth_of_answers`: the UPPER bound is below 10% — reachable only while `tailIsProvable` is true. `share_not_yet_separable`: the range straddles a line — a real company, sometimes named, that the evidence cannot yet place; this is the group that can still be moved. The token names a measured condition about a third party, never a verdict: say ‘named in under a tenth of answers’, never ‘irrelevant’ or ‘tail’. Thresholds are the same for every project. Values: `named_in_a_quarter_or_more_of_answers`, `named_in_under_a_tenth_of_answers`, `share_not_yet_separable`.
`domain`	`string`	Brand domain — the identity every count is matched on.
`name`	`string`	Brand name as the models most recently wrote it.
`isOwn`	`boolean`	Whether this is the customer’s own row. The customer’s row is ALWAYS on the map, at zero when no answer named them — that zero is a measured finding.
`rankByPresence`	`number \| null`	Rank by how often the brand is named: one plus the number of brands named more often. Ties SHARE a rank — several brands at the same share read as one rank, never as consecutive ones — so say ‘7th of 9 by how often it is named’, and never break a tie. Null at zero presence: a brand no answer in the window named has no place in this order, so say ‘not named in any answer’, never a rank. Only the customer’s own row can sit there, because every other row is on the map because an answer named it — and that row stays on the map, since its zero is measured. Nullable.
`perEngine`	`object`	This brand on each AI model that answered in the window. The pooled figures above are a vote across models — which AI models back a row — and a brand core to one model and a brand core to all of them look identical on the pooled figure, so read this before saying a brand is ‘core to the market’. A model absent here returned no usable answer in the window; a slice at zero is a model that answered and never named the brand. Nested — see the Example tab.
`endorsement`	`object \| null`	How warmly the models that describe brands recommend this one, on a scale from 21 to 100: the tone each answer gave it (highly recommended down to merely mentioned) and the role (a direct pick down to a fallback), weighted and averaged over the answers in the window that carried both, pooled the same way as `presence`. THE SCALE HAS A FLOOR, NOT A ZERO — a bare mention offered as a fallback still scores 21 — so read a low figure against 21, never against 0, and NEVER set it against `presence`: the two are different units, and a brand named in under 21% of answers sits on one side of any such comparison by arithmetic alone. There is no gap between them to report. It is the models’ own labels on their own answers, not an independent assessment of the brand. `null` means no answer in the window described the brand — named only by a model that describes nobody, or not named at all — never a low reading. Say ‘the models describe it as a fallback option’ from a figure near the floor, and ‘as a leading choice’ near 100; the state named on `customerStanding` is the comparison to make for the customer’s own row. Nullable. Nested — see the Example tab.
`pricePerception`	`object \| null`	Where the models that describe brands place this one’s price (shown in the app as ‘Price read’) — the tier they stated most often, with the mean’s position on a line from free (0) through budget, mid-range and premium to enterprise (100), pooled the same way as `presence`. What the models THINK it costs, never its price list: the scale has one thin independent witness and is not validated beyond the cheap end. `null` means no answer in the window stated a tier for it, never ‘free’. Report the tier word with its share of the answers, and say the models disagree when `tierAnswers` is under half of `answersRead`. Nullable. Nested — see the Example tab.

item.summary.marketMap.brandsPage — object

Field	Type	Description
`offset`	`number`	Rows skipped before this page, in stored order.
`limit`	`number`	Rows asked for. The page can hold more: rows its list always keeps — the customer’s own, where the list has one, and on the AI Visibility market map and history every tracked competitor’s — when they fall outside the page.
`total`	`number`	Rows in the whole list (after any filter), not on this page.
`hasMore`	`boolean`	Whether rows exist after this page. Ask for them with a higher offset.

item.customerStanding.endorsement.explanation — object

Field	Type	Description
`code`	`string`	Stable code for the sentence — the state token.
`text`	`string`	The sentence, rendered verbatim by every surface.

item.customerStanding.price.explanation — object

Field	Type	Description
`code`	`string`	Stable code for the sentence — the state token.
`text`	`string`	The sentence, rendered verbatim by every surface.

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

Field	Type	Description
`axis`	`string`	The axis the model framed this brand as competing on. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.

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

Field	Type	Description
`keywords`	`array<string>`	Keywords the model associated with this brand (up to 5). Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	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` · `not_found`	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. 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.

Returns · { readingGuide, items, pagination, truncated }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`page`	`number`	Page number (1-indexed). Default `1`. Min `1`.
`limit`	`number`	Number of items per page. Default `20`. Range `1`–`100`.
`view`	`string`	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`. Values: `compact`, `full`.

Request


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

Response 200 OK

Example


{
  "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": [
            {
              "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
        },
        "mentionRateGap": -22.2,
        "totalCompetitorsFound": 8,
        "totalQueries": 12,
        "totalEntries": 45,
        "competitorRankings": [
          {
            "domain": "competitor.com",
            "name": "Competitor Inc",
            "isOwn": false,
            "mentionCount": 7,
            "mentionRate": 77.8,
            "aiScore": 68,
            "isTracked": false
          }
        ],
        "promptMarket": {
          "state": "rivals_named_in_most_answers",
          "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",
              "state": "answers_and_rival_list_disagree",
              "explanation": {},
              "answersNamingAnyRival": 1,
              "answersMatchingCurrentPromptText": 20
            }
          ]
        },
        "competitorRankingsPage": {
          "offset": 0,
          "limit": 10,
          "total": 96,
          "hasMore": true
        }
      }
    }
  ],
  "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 — the dashboard summary without `marketMap`, which is on the dashboard and on a check’s detail. 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`	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 it is the ask — every AI model the check asked × every prompt it ran — minus the queries a model was read for and had no answer to show (`noAnswerShown`); 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.
`totalEntries`	`number`	Total brand entries across this check’s counted answers — one per brand a model named, summed over every answer. This is the size preview for `includeAnswers=true`: an entry serializes to about 1,500 characters. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which this count does not predict and which the `brand=` filter keeps by design.
`competitorRankings`	`array<object>`	Every brand this check’s counted answers named, plus the customer’s own row, in the ORDER TO RENDER: `mentionRate` desc, then `aiScore` desc, then domain. One check’s view; the windowed view with its uncertainty is `marketMap`. Nothing here is positional, so never re-sort or compare rows by position. See `items[].summary.competitorRankings[]`.
`promptMarket`	`object`	Whether this project’s prompts are reaching the market its tracked competitor list describes — a reading about the QUESTIONS we ask, not about the brand’s visibility. Every other number in this summary is arithmetic over those prompts, so this is the field that says whether they are measuring the right market at all. ABSENT means no reading could be produced: the account tracks no competitors to test the prompts against, or no answer came back to test them with. There is deliberately no token for that case, so absence is the only way it is expressed — and absence NEVER means the prompts are fine. Do not report a missing `promptMarket` as a pass, and do not infer one from the numbers beside it. This reading suppresses nothing: everything else in this summary is complete and published whatever it says, because a customer may have chosen unusual prompts deliberately and their data is the only evidence they can judge that on. See `items[].summary.promptMarket`.
`competitorRankingsPage`	`object`	Compact view only: which of the check’s ranked companies `competitorRankings` carries — the first 10 in stored order, then every tracked company and the customer’s own row that fall outside them, still in stored order. `total` counts every row of the stored list — every company the check named; `hasMore` is true only when rows were left out. There is no offset: the whole list is `view=full`, or the check’s detail. The compact row also leaves out `promptMarket.perPrompt`, which the dashboard and the check’s detail carry. See `items[].summary.competitorRankingsPage`.

items[].summary.customer — object

Field	Type	Description
`domain`	`string`	Customer domain
`mentionRate`	`number`	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 number. Under the full-coverage gate (a check publishes only once every query it asked was read) that is the ask — every AI model the check asked × its recorded prompt count — MINUS the queries a model was read for and had no answer to show (`noAnswerShown`); 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’. A `0` is a real rate: none of the answers this check counted named this brand.
`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`	AI Visibility Score, 0-100. 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. Averaged over the answers this check counted and smoothed over up to the last 5 published checks. Present on every published check, and a `0` is a measured score — never ‘unscored’. 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 it to tell that case from a brand no counted answer named.
`perProvider`	`object`	Per-model breakdown, one entry per AI model this check asked. A model is ABSENT when the check did not ask it — checks keep the model set they were run with, so a check from before a model was added carries no entry for it. Absent means not measured; never read it as ‘not mentioned’. A model that is PRESENT with `mentioned: false` is read together with its `answersCounted`: beside a non-zero count it answered and did not name the customer, beside `answersCounted: 0` it was read and had no answer to show on every prompt, which is not a measurement of the customer at all. 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. One row per prompt the check asked, so the array length is that check’s own prompt count. 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`	Top competitor mention rate percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent.

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
`mentionCount`	`number`	Total mentions across the answers this check counted.
`mentionRate`	`number`	Mention rate as percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. This row names a THIRD PARTY: a `0` here is a measured rate — none of the answers this check counted named them — and must be reported as exactly that.
`aiScore`	`number`	AI Visibility Score (0-100), on the same rule as `customer.aiScore`. 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. This row names a THIRD PARTY, so the reading matters more here than anywhere else on the response. 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. Reporting a `0` as ‘never named’ is a false claim about another company published under our name. 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.
`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.promptMarket — object

Field	Type	Description
`state`	`string`	Which of the three readings this evidence supports. `rivals_named_in_most_answers` — most of the answers named at least one company the account tracks, so the numbers beside this are measuring the intended competition. `rival_match_too_close_to_call` — some answers named a tracked competitor and some named none, in a proportion this much evidence cannot separate; an undecided reading, not a milder version of the next one. `answers_and_rival_list_disagree` — almost none of the answers named a tracked competitor. That last one does NOT assert that the prompts are wrong. It compares two things the customer supplied, the prompts and the tracked competitor list, so a disagreement means one of them does not match what the models said and this comparison cannot tell you which. A narrow market that genuinely does not come up in AI answers yet produces the same reading, and that is a real finding rather than a defect. Report the disjunction, and point at the stored answers (`includeAnswers=true`) — they are the evidence that settles it. Values: `rivals_named_in_most_answers`, `rival_match_too_close_to_call`, `answers_and_rival_list_disagree`.
`explanation`	`object`	The sentence to report for this reading, with a stable code beside it. This is payload rather than documentation: it is the only place the reading is expressed in words, and the app, this API and the MCP tools all say these same words. Render `text` verbatim. See `items[].summary.promptMarket.explanation`.
`answersNamingAnyRival`	`number`	How many of the answers behind this reading named at least one company the account tracks. Membership, not volume: an answer that named four tracked competitors counts once, exactly like an answer that named one. It says NOTHING about the customer’s own visibility — a window in which every answer named a rival and none named the customer reads healthy here and 0% under `customer.mentionRate`. Never present it as a mention rate, and never pair it with `totalQueries`, which counts a different set over a different window.
`answersMatchingCurrentPromptText`	`number`	Divide `answersNamingAnyRival` by THIS figure and nothing else. It is the universe that numerator is drawn from: answers across this reading’s window of checks that were produced by the account’s prompts as their text stands TODAY. Two exclusions. A query that produced no usable answer is out entirely and is never counted as an answer that named nobody. An answer produced before the customer last edited a prompt is also out, because it answers a question nobody is asking any more. THIS RESPONSE CARRIES A SECOND ANSWER COUNT drawn from the same window — `marketMap.answersReceived`, which pools every usable answer whatever wording produced it, and is the divisor for brand presence. This figure is never larger than that one and is EQUAL to it whenever no prompt has been reworded inside the window, which is the steady state; seeing the two agree does not mean they are the same field. A difference means a prompt’s text changed inside the window, and the size of the difference is how many answers that edit orphaned. Also unrelated to `totalQueries` above, which counts ONE check’s answers while this counts a window of them.
`checksAnalysed`	`number`	How many published checks this reading was drawn from. Checks, never days — checks are not daily, and the interval is a schedule setting. Quote it whenever you quote the reading: a low number is the usual reason a reading comes back `rival_match_too_close_to_call`, and that state describes thin evidence rather than weak prompts. Counts the checks that contributed an answer on today’s prompt text, so it can sit BELOW `marketMap.checksAnalysed`, which counts every check that contributed any usable answer. The two are drawn from one window and agree unless a prompt was reworded inside it.
`perPrompt`	`array<object>`	One reading per prompt, each with its own `state` — every prompt this reading could attribute answers to appears here, whether it is reaching the tracked competitor list, failing to, or not yet separable. Read each entry’s `state` and report its `explanation.text` verbatim: do NOT treat membership of this list as a fault, because the healthy and the undecided readings are in it too. A prompt is MISSING for exactly one reason — no answer in the window was produced by its current wording, which is what happens for a while after the customer edits it — so absence means ‘no evidence for this prompt yet’ and never a verdict. An empty array means that was true of every prompt; the array being absent means it was true of the check as a whole. An undecided entry still carries its counts, and those counts are evidence of how thin the sample is, never a position: three answers cannot rank one prompt against another, and presenting a partial share as a score is the error this state exists to prevent. Note that entries make a history row several times larger and appear on every project, so a page of history may hit the response size cap sooner — lower `limit` if `truncated` comes back true. See `items[].summary.promptMarket.perPrompt[]`.

items[].summary.competitorRankingsPage — object

Field	Type	Description
`offset`	`number`	Rows skipped before this page, in stored order.
`limit`	`number`	Rows asked for. The page can hold more: rows its list always keeps — the customer’s own, where the list has one, and on the AI Visibility market map and history every tracked competitor’s — when they fall outside the page.
`total`	`number`	Rows in the whole list (after any filter), not on this page.
`hasMore`	`boolean`	Whether rows exist after this page. Ask for them with a higher offset.

items[].summary.customer.perProvider — object

Field	Type	Description
`openai`	`object`	ChatGPT metrics. Nested — see the Example tab.
`claude`	`object`	Claude metrics. Nested — see the Example tab.
`gemini`	`object`	Gemini metrics. Nested — see the Example tab.
`perplexity`	`object`	Perplexity metrics. Nested — see the Example tab.
`google_ai_overviews`	`object`	Google AI Overviews 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 where the model answered, but a model with `answersCounted: 0` under `perProvider` was read and had no answer to show on this check, and on a check published before that gate it could be an answer that never arrived.
`score`	`number`	0-100 position score for this prompt, averaged over the models whose answers this check counted — never over a fixed model count. Higher is better. 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. So it is not a rank and not a percentage of anything. 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. `mentionedBy` separates the two: non-empty means the models named them here. 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`.

items[].summary.promptMarket.explanation — object

Field	Type	Description
`code`	`string`	Stable identifier for this sentence. Branch on it if you need to; never substitute your own wording for it. The project-level reading and a per-prompt reading carry DIFFERENT codes even where their `state` matches, so the two are not interchangeable and de-duplicating a list by code will not collapse them.
`text`	`string`	The sentence to report, in the words every CompetLab surface uses. Render it VERBATIM — do not paraphrase it, shorten it, or compose your own sentence from `state`. The wording is chosen to say only what this comparison can support, and a rewrite reliably says more than that. It carries no fraction and no percentage on purpose: this dimension’s headline metric is itself a count of answers, so a number inside this sentence gets read as a visibility rate. The counts are the sibling fields — put them beside the sentence, never inside it.

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

Field	Type	Description
`promptId`	`string`	Stable identifier for the prompt, minted once and kept for the life of that prompt — including when its wording is rewritten. It is the durable way to follow one prompt across checks. Note that the project endpoint returns prompt TEXTS and no ids, so lining a row up with a project’s current prompts means matching on `promptTextInProject` below.
`promptTextInProject`	`string`	The prompt’s wording as the project holds it now — which is also the wording every answer behind this reading was produced by, because answers produced by wording that has since been rewritten are excluded from it. Quote it so a reader can find the prompt in the project’s settings, and match on it to line this row up with the project endpoint’s prompt list. It will always match a current prompt; `promptId` is the durable handle if you need to follow one across edits.
`state`	`string`	This prompt’s own reading, on the same three-token scale as the project-level `state` and read in exactly the same way. Computed over the answers to THIS prompt alone, so it can differ from the project-level reading — which is the whole reason to look here. Values: `rivals_named_in_most_answers`, `rival_match_too_close_to_call`, `answers_and_rival_list_disagree`.
`explanation`	`object`	The sentence to report for this prompt, rendered verbatim like the project-level one. It is deliberately IDENTICAL for every prompt in the same state and never names the prompt — `promptId` and `promptTextInProject` do that. Say it once over a list of prompts rather than repeating a near-identical paragraph per row. Nested — see the Example tab.
`answersNamingAnyRival`	`number`	Answers to THIS prompt that named at least one company the account tracks. Membership, not volume: an answer that named four tracked competitors counts once, exactly like an answer that named one.
`answersMatchingCurrentPromptText`	`number`	Divide `answersNamingAnyRival` by THIS figure and nothing else. It is the universe that numerator is drawn from: answers to this prompt as its text stands TODAY. Two exclusions. A query that produced no usable answer is out entirely and is never counted as an answer that named nobody. An answer produced before the customer last edited this prompt’s text is also out, because it answers a question nobody is asking any more. Do not compare it to a figure on the market map: this row covers ONE prompt while the map pools every prompt, so it is a fraction of the map’s total by construction and that gap is not evidence of anything.

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: the market map as it stood at this check under summary.marketMap, and each competitor’s mention rate and AI Visibility Score across every AI model we query under summary.competitorRankings — in the order to render, nothing positional. 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. These rows name other companies, so reporting a 0 as ‘never named’ is a false claim about a third party published under CompetLab’s name. 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. 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, and how large depends on the project. An entry is one brand a model named, at about 1,500 characters each — so the block grows with three things at once: how many prompts the project asks — 8 on every plan and in the trial — times five models, how many models answered, and how many companies each answer named. No figure quoted here can stand in for summary.totalEntries; read it and size the fetch from it. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which totalEntries does not predict and which the brand filter keeps by design. Then 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, and queries the model was read for and had no answer to show — today, prompts Google showed no AI Overview for — in noAnswerShown, excluded from every count and not a failure; those are three different facts, and an empty brands under a brand filter is none of them. summary.customer.perPrompt 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, and how large depends on the project. An entry is one brand a model named, at about 1,500 characters each — so the block grows with three things at once: how many prompts the project asks — 8 on every plan and in the trial — times five models, how many models answered, and how many companies each answer named. No figure quoted here can stand in for `summary.totalEntries`; read it and size the fetch from it. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which `totalEntries` does not predict and which the `brand=` filter keeps by design. 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`, `perplexity`, `google_ai_overviews`.
`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: it keeps at most one brand entry per answer instead of every brand the model named, and none at all on the answers that did not name it. Compare `summary.totalEntries` with the answer count to see the saving on this check. Google AI Overviews answers still carry their overview text and cited pages, which this filter keeps by design.
`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.
`view`	`string`	How much of the response to return. `compact`: `summary.marketMap.brands` is one page of rows — the core by default — with `summary.marketMap.brandsPage` saying where it sits; the customer’s own row and every tracked competitor’s are always included. Every other field is unchanged, and `untrackedCoreBrands` and `customerStanding` are still read from the whole map. `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`. Values: `compact`, `full`.
`mapOffset`	`number`	Rows of `summary.marketMap.brands` to skip, in the order the list is stored. Default 0. Pages the compact view: sent without `view` it selects the compact view, and beside `view=full` it is refused with `paging_requires_compact_view`. Min `0`.
`mapLimit`	`number`	Rows of `summary.marketMap.brands` to return, 1 to 200. Default the core size (`summary.marketMap.coreSize`), and never fewer than 10. Pages the compact view: sent without `view` it selects the compact view, and beside `view=full` it is refused with `paging_requires_compact_view`. Range `1`–`200`.
`includeSummary`	`boolean`	Whether to return `summary`. Omitted, `/v1` returns it unless `includeAnswers=true` — a read for the answers rarely needs the summary again, and the summary is most of the response — and a param that pages a summary list returns it too. Set it explicitly to override; `false` beside a paging param is refused with `paging_requires_summary`.

Request


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

Response 200 OK

Example


{
  "item": {
    "readingGuide": {
      "summary.pages": "Pages the engines RETRIEVED while answering, never pages they cited."
    },
    "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": [
          {
            "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
      },
      "mentionRateGap": -22.2,
      "totalCompetitorsFound": 8,
      "totalQueries": 12,
      "totalEntries": 45,
      "competitorRankings": [
        {
          "domain": "competitor.com",
          "name": "Competitor Inc",
          "isOwn": false,
          "mentionCount": 7,
          "mentionRate": 77.8,
          "aiScore": 68,
          "isTracked": false
        }
      ],
      "promptMarket": {
        "state": "rivals_named_in_most_answers",
        "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",
            "state": "answers_and_rival_list_disagree",
            "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
          }
        ]
      },
      "marketMap": {
        "checksAnalysed": 5,
        "answersReceived": 60,
        "tailIsProvable": true,
        "coreSize": 9,
        "perEngine": {
          "openai": {
            "answersReceived": 15
          },
          "claude": {
            "answersReceived": 15
          },
          "gemini": {
            "answersReceived": 15
          },
          "perplexity": {
            "answersReceived": 15
          },
          "google_ai_overviews": {
            "answersReceived": 15
          }
        },
        "profileEngines": [
          "openai",
          "claude",
          "gemini",
          "perplexity"
        ],
        "brands": [
          {
            "answersNaming": 31,
            "answersReceived": 60,
            "presence": 52,
            "presenceLow": 40,
            "presenceHigh": 63,
            "zone": "named_in_a_quarter_or_more_of_answers",
            "domain": "sienge.com.br",
            "name": "Sienge",
            "isOwn": false,
            "rankByPresence": 2,
            "perEngine": {
              "openai": {},
              "claude": {},
              "gemini": {},
              "perplexity": {},
              "google_ai_overviews": {}
            },
            "endorsement": {
              "value": 64,
              "answersRead": 9,
              "low": 51,
              "high": 77
            },
            "pricePerception": {
              "value": 64,
              "answersRead": 9,
              "low": 51,
              "high": 77,
              "tier": "mid_range",
              "tierAnswers": 6
            }
          }
        ],
        "brandsPage": {
          "offset": 0,
          "limit": 10,
          "total": 96,
          "hasMore": true
        }
      }
    },
    "answers": [
      {
        "provider": "openai",
        "promptIndex": 0,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "answerText": "For mid-market sales teams, forecasting platforms such as Competitor Inc, Rival Software and Example Analytics combine CRM data with AI-driven projections.",
        "askedIn": {
          "locationName": "United States",
          "languageName": "English"
        },
        "sources": [
          {
            "url": "https://www.g2.com/categories/sales-forecasting",
            "domain": "g2.com",
            "title": "Best Sales Forecasting Software"
          }
        ],
        "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"
      }
    ],
    "noAnswerShown": [
      {
        "provider": "google_ai_overviews",
        "promptIndex": 1,
        "promptText": "best sales forecasting platforms for mid-market teams",
        "reason": "no_ai_overview_shown"
      }
    ],
    "providerStatus": {
      "openai": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "claude": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "gemini": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "perplexity": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      },
      "google_ai_overviews": {
        "reported": true,
        "completedAt": "2026-03-15T10:00:00.000Z",
        "answersCounted": 3,
        "noAnswerShown": 0,
        "brandsNamed": 21
      }
    },
    "answerCoverage": {
      "queriesSent": 12,
      "answersCounted": 8
    },
    "answersTruncated": false
  }
}

Fields

item — object

Field	Type	Description
`readingGuide`	`object`	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.
`checkId`	`string`	Check ID
`completedAt`	`string`	When this check completed (ISO-8601)
`summary`	`object`	Check summary statistics, including the market map as it stood at this check under `summary.marketMap`, and each competitor’s mention rate and AI Visibility Score under `summary.competitorRankings` — in the order to render, nothing positional. ABSENT when `includeSummary` is false — by default whenever `includeAnswers=true`. 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` and `noAnswerShown`. `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` and `noAnswerShown` 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. Per-brand prose — description, ranking rationale, audience, pricing tier, messaging, differentiation — is present only for models that describe brands; a brand row carrying only `rank`, `name` and `domain` means Google AI Overviews named it in prose, and the prose is on that answer’s `answerText`. ATTRIBUTION: every piece of prose in this block — descriptions, ranking rationales, audiences, claims, and the overview text itself — 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 was read — answered, or listed under `noAnswerShown` — which is the normal case, because a check is only scored when every query it asked was read. 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 and `noAnswerShown.length` recovers the queries sent — but a shortfall written as a fraction, 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[]`.
`noAnswerShown`	`array<object>`	Queries the model was read for and had no answer to show — today, prompts for which Google’s results page carried no AI Overview. Not a failure and not an answer: these slots are excluded from every count on this payload. Separate from `unansweredQueries`, which are queries we could not measure. Present ONLY when `includeAnswers=true`. Narrowed by `provider` and `promptIndex`, never by `brand`. An empty array means every query the check sent was either answered or could not be measured. See `item.noAnswerShown[]`.
`providerStatus`	`object`	Per-model reporting status for this check: which of the models this check asked returned data, when, and how much. One entry per model the check ASKED — a model is absent when the check did not ask it, because checks keep the model set they were run with; absent means not measured, never ‘did not report’. Present ONLY when `includeAnswers=true`. It carries no visibility judgement, and it is NOT narrowed by the filters — it always describes every model the check asked 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 — both read from the check’s own record of its ask, never inferred from the length of `answers`. Present ONLY when `includeAnswers=true`. 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 answers were dropped from the end of `answers`. The cut lands on a WHOLE PROMPT ROUND, never inside one: `answers` is ordered prompt by prompt across the models, so truncation drops the highest `promptIndex` values and no model is ever removed by truncation from a prompt that is still present — group the array by `promptIndex` and no round is short. A model missing from a prompt that IS present is in `unansweredQueries` or `noAnswerShown`, not cut; neither of those arrays is ever truncated, so a prompt absent from `answers` is not a prompt no model answered. Individual `brands` lists are never partially truncated. `summary`, `providerStatus` and `answerCoverage` are never affected. Narrow the response with `provider` or `promptIndex` to get a complete view — `brand` keeps every answer, and each Google AI Overviews answer’s overview text and cited pages with it, so it shrinks the payload far less. 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`	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 it is the ask — every AI model the check asked × every prompt it ran — minus the queries a model was read for and had no answer to show (`noAnswerShown`); 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.
`totalEntries`	`number`	Total brand entries across this check’s counted answers — one per brand a model named, summed over every answer. This is the size preview for `includeAnswers=true`: an entry serializes to about 1,500 characters. Google AI Overviews answers additionally carry the overview text and the pages Google cited, which this count does not predict and which the `brand=` filter keeps by design.
`competitorRankings`	`array<object>`	Every brand this check’s counted answers named, plus the customer’s own row, in the ORDER TO RENDER: `mentionRate` desc, then `aiScore` desc, then domain. One check’s view; the windowed view with its uncertainty is `marketMap`. Nothing here is positional, so never re-sort or compare rows by position. See `item.summary.competitorRankings[]`.
`promptMarket`	`object`	Whether this project’s prompts are reaching the market its tracked competitor list describes — a reading about the QUESTIONS we ask, not about the brand’s visibility. Every other number in this summary is arithmetic over those prompts, so this is the field that says whether they are measuring the right market at all. ABSENT means no reading could be produced: the account tracks no competitors to test the prompts against, or no answer came back to test them with. There is deliberately no token for that case, so absence is the only way it is expressed — and absence NEVER means the prompts are fine. Do not report a missing `promptMarket` as a pass, and do not infer one from the numbers beside it. This reading suppresses nothing: everything else in this summary is complete and published whatever it says, because a customer may have chosen unusual prompts deliberately and their data is the only evidence they can judge that on. See `item.summary.promptMarket`.
`marketMap`	`object`	THE MARKET MAP — which companies the AI models recommend in this project’s category, how often each is named over the last few checks, where the customer sits among them, and which of those companies the project is not tracking. Lead with it: ‘Nine companies make up this market as the AI models draw it; the customer is one of them, 7th of 9 by how often it is named.’ Every share is a share of answers analysed with its range beside it; two brands whose ranges overlap are not ordered. Read `promptMarket` first: if it is not `rivals_named_in_most_answers`, say the prompts may not describe this project’s market and that the map below cannot be trusted — a confident map of the wrong market is the worst output this product can produce. Not returned on history rows; see the dashboard or a check’s detail. See `item.summary.marketMap`.

item.answers[] — each entry

Field	Type	Description
`provider`	`string`	Which AI produced this answer. Values: `openai`, `claude`, `gemini`, `perplexity`, `google_ai_overviews`.
`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.
`answerText`	`string`	The answer as the model wrote it. Present for Google AI Overviews: the overview text, verbatim, from which the brands below were read in order of first mention. Absent for models that answer in a ranked list. Model prose, attributed to the model that wrote it.
`askedIn`	`object`	The Google market the question was asked in. Google AI Overviews only. See `item.answers[].askedIn`.
`sources`	`array<object>`	The pages cited beside this answer. Google AI Overviews only — the pages Google cited with the overview, distinct by URL, up to 20. ABSENT means either that Google listed no citations or that every one it listed was a masked redirect we could not resolve to a page — never that Google cited nothing. An EMPTY array is the measured ‘it cited nothing’. Absent for every other model. See `item.answers[].sources[]`.
`brands`	`array<object>`	Brands this model named, in the order it ranked them — for Google AI Overviews, in the order of first mention in `answerText`, each carrying only `name` and `domain`. Every answer in this array arrived — a query that produced nothing is not here at all, it is in `unansweredQueries`, and a query the model was read for and had no answer to show is in `noAnswerShown`. 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`, `perplexity`, `google_ai_overviews`.
`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 model 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.noAnswerShown[] — each entry

Field	Type	Description
`provider`	`string`	Which AI this query was sent to — we reached it and it had no answer to show. Values: `openai`, `claude`, `gemini`, `perplexity`, `google_ai_overviews`.
`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_ai_overview_shown` — Google’s results page for this prompt carried no AI Overview. A measured fact about the prompt on Google that day: not a failure, not an answer, and nothing the customer’s prompt did wrong. Report it as ‘Google showed no AI Overview for this question — not counted’; NEVER as ‘not mentioned’, ‘0 mentions’, or a query that failed. This query is excluded from every count and rate on this response. Values: `no_ai_overview_shown`.

item.providerStatus — object

Field	Type	Description
`openai`	`object`	ChatGPT. See `item.providerStatus.openai`.
`claude`	`object`	Claude. See `item.providerStatus.claude`.
`gemini`	`object`	Gemini. See `item.providerStatus.gemini`.
`perplexity`	`object`	Perplexity. See `item.providerStatus.perplexity`.
`google_ai_overviews`	`object`	Google AI Overviews. See `item.providerStatus.google_ai_overviews`.

item.answerCoverage — object

Field	Type	Description
`queriesSent`	`number`	Queries this check sent: every AI model it queried, against every prompt it ran — read the number from this field; do not recompute it from today’s model count, which is not necessarily that check’s. Checks keep the model set and the prompt count they were run with.
`answersCounted`	`number`	Queries that came back with an answer we could use. The shortfall is `queriesSent` − `answersCounted`, and it is two different facts added together: `queriesSent` − `answersCounted` = `unansweredQueries.length` + `noAnswerShown.length` — queries we could not measure, plus queries the model was read for and had no answer to show. On a check published under the full-coverage gate the whole shortfall is in `noAnswerShown`; on older checks it can exceed both arrays together, because a model that failed before answering anything recorded no query slots to list. Trust the shortfall, not the array lengths. NEVER present these numbers as a fraction: this dimension’s headline metric is already an n-of-N over the same denominator, so any shortfall written as a fraction gets read as a visibility rate. State them as separate facts that cannot be divided by each other — “We sent every query we planned; Google showed no AI Overview for one of them, so it is not counted”, or, for a query that could not be read, “one 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`	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 number. Under the full-coverage gate (a check publishes only once every query it asked was read) that is the ask — every AI model the check asked × its recorded prompt count — MINUS the queries a model was read for and had no answer to show (`noAnswerShown`); 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’. A `0` is a real rate: none of the answers this check counted named this brand.
`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`	AI Visibility Score, 0-100. 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. Averaged over the answers this check counted and smoothed over up to the last 5 published checks. Present on every published check, and a `0` is a measured score — never ‘unscored’. 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 it to tell that case from a brand no counted answer named.
`perProvider`	`object`	Per-model breakdown, one entry per AI model this check asked. A model is ABSENT when the check did not ask it — checks keep the model set they were run with, so a check from before a model was added carries no entry for it. Absent means not measured; never read it as ‘not mentioned’. A model that is PRESENT with `mentioned: false` is read together with its `answersCounted`: beside a non-zero count it answered and did not name the customer, beside `answersCounted: 0` it was read and had no answer to show on every prompt, which is not a measurement of the customer at all. 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. One row per prompt the check asked, so the array length is that check’s own prompt count. 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`	Top competitor mention rate percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent.

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
`mentionCount`	`number`	Total mentions across the answers this check counted.
`mentionRate`	`number`	Mention rate as percentage. Same divisor as `customer.mentionRate` — the answers this check counted, not the queries sent. This row names a THIRD PARTY: a `0` here is a measured rate — none of the answers this check counted named them — and must be reported as exactly that.
`aiScore`	`number`	AI Visibility Score (0-100), on the same rule as `customer.aiScore`. 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. This row names a THIRD PARTY, so the reading matters more here than anywhere else on the response. 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. Reporting a `0` as ‘never named’ is a false claim about another company published under our name. 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.
`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.summary.promptMarket — object

Field	Type	Description
`state`	`string`	Which of the three readings this evidence supports. `rivals_named_in_most_answers` — most of the answers named at least one company the account tracks, so the numbers beside this are measuring the intended competition. `rival_match_too_close_to_call` — some answers named a tracked competitor and some named none, in a proportion this much evidence cannot separate; an undecided reading, not a milder version of the next one. `answers_and_rival_list_disagree` — almost none of the answers named a tracked competitor. That last one does NOT assert that the prompts are wrong. It compares two things the customer supplied, the prompts and the tracked competitor list, so a disagreement means one of them does not match what the models said and this comparison cannot tell you which. A narrow market that genuinely does not come up in AI answers yet produces the same reading, and that is a real finding rather than a defect. Report the disjunction, and point at the stored answers (`includeAnswers=true`) — they are the evidence that settles it. Values: `rivals_named_in_most_answers`, `rival_match_too_close_to_call`, `answers_and_rival_list_disagree`.
`explanation`	`object`	The sentence to report for this reading, with a stable code beside it. This is payload rather than documentation: it is the only place the reading is expressed in words, and the app, this API and the MCP tools all say these same words. Render `text` verbatim. See `item.summary.promptMarket.explanation`.
`answersNamingAnyRival`	`number`	How many of the answers behind this reading named at least one company the account tracks. Membership, not volume: an answer that named four tracked competitors counts once, exactly like an answer that named one. It says NOTHING about the customer’s own visibility — a window in which every answer named a rival and none named the customer reads healthy here and 0% under `customer.mentionRate`. Never present it as a mention rate, and never pair it with `totalQueries`, which counts a different set over a different window.
`answersMatchingCurrentPromptText`	`number`	Divide `answersNamingAnyRival` by THIS figure and nothing else. It is the universe that numerator is drawn from: answers across this reading’s window of checks that were produced by the account’s prompts as their text stands TODAY. Two exclusions. A query that produced no usable answer is out entirely and is never counted as an answer that named nobody. An answer produced before the customer last edited a prompt is also out, because it answers a question nobody is asking any more. THIS RESPONSE CARRIES A SECOND ANSWER COUNT drawn from the same window — `marketMap.answersReceived`, which pools every usable answer whatever wording produced it, and is the divisor for brand presence. This figure is never larger than that one and is EQUAL to it whenever no prompt has been reworded inside the window, which is the steady state; seeing the two agree does not mean they are the same field. A difference means a prompt’s text changed inside the window, and the size of the difference is how many answers that edit orphaned. Also unrelated to `totalQueries` above, which counts ONE check’s answers while this counts a window of them.
`checksAnalysed`	`number`	How many published checks this reading was drawn from. Checks, never days — checks are not daily, and the interval is a schedule setting. Quote it whenever you quote the reading: a low number is the usual reason a reading comes back `rival_match_too_close_to_call`, and that state describes thin evidence rather than weak prompts. Counts the checks that contributed an answer on today’s prompt text, so it can sit BELOW `marketMap.checksAnalysed`, which counts every check that contributed any usable answer. The two are drawn from one window and agree unless a prompt was reworded inside it.
`perPrompt`	`array<object>`	One reading per prompt, each with its own `state` — every prompt this reading could attribute answers to appears here, whether it is reaching the tracked competitor list, failing to, or not yet separable. Read each entry’s `state` and report its `explanation.text` verbatim: do NOT treat membership of this list as a fault, because the healthy and the undecided readings are in it too. A prompt is MISSING for exactly one reason — no answer in the window was produced by its current wording, which is what happens for a while after the customer edits it — so absence means ‘no evidence for this prompt yet’ and never a verdict. An empty array means that was true of every prompt; the array being absent means it was true of the check as a whole. An undecided entry still carries its counts, and those counts are evidence of how thin the sample is, never a position: three answers cannot rank one prompt against another, and presenting a partial share as a score is the error this state exists to prevent. Note that entries make a history row several times larger and appear on every project, so a page of history may hit the response size cap sooner — lower `limit` if `truncated` comes back true. See `item.summary.promptMarket.perPrompt[]`.

item.summary.marketMap — object

Field	Type	Description
`checksAnalysed`	`number`	Published checks pooled into this map — this check plus up to the previous 4. Checks, never days: the interval is a schedule setting, and a three-day and a monthly project showing the same `answersReceived` are looking at equally trustworthy maps.
`answersReceived`	`number`	Usable answers pooled across those checks and every AI model — the total every pooled `presence` on `brands` divides by. Quote it whenever you quote a share. This counts EVERY usable answer in the window, whatever prompt wording produced it, which is what a market picture needs: an answer naming a rival is evidence about the market even if the question that drew it has since been reworded. `promptMarket.answersMatchingCurrentPromptText` counts the narrower set produced by today’s wording over the same window, so it is never larger than this and is equal whenever no prompt has been reworded — the two agreeing is the steady state, not a sign they are one field. Divide a brand’s `answersNaming` by THIS figure and nothing else.
`tailIsProvable`	`boolean`	Whether the sample is large enough for ANY brand to reach `named_in_under_a_tenth_of_answers` — the upper bound of a brand named in exactly one answer falls below 10% — 56 answers with the interval used, on the rounded bounds this response carries. While false no brand is in that zone, and the honest sentence is ‘no brand can be ruled out of this market yet’ — never ‘tail’, never ‘irrelevant’.
`coreSize`	`number`	Brands in `named_in_a_quarter_or_more_of_answers` — the size of the market as the models draw it. Lead with it: ‘Nine companies make up this market as the AI models draw it.‘
`perEngine`	`object`	Usable answers per AI model in the window. A model absent here returned no usable answer in the window. See `item.summary.marketMap.perEngine`.
`profileEngines`	`array<string>`	The AI models the `endorsement` and `pricePerception` readings on `brands` were read from — those with at least one usable answer in the window that described a company. A model that names companies without describing them (Google AI Overviews) is never here, and a model that returned no usable answer in the window is not here either. Name them whenever you quote a reading. Empty means no answer in the window described anybody, and every reading on `brands` is `null`.
`brands`	`array<object>`	Every brand any answer in the window named, plus the customer’s own row, in the ORDER TO RENDER: `presence` desc, then domain. Never re-sort it by anything positional — there is nothing positional to sort by, by design. Read `isOwn` to find the customer; `rankByPresence` says where they sit and shares its value across ties, and is null on a row named in no answer. See `item.summary.marketMap.brands[]`.
`brandsPage`	`object`	Compact view only: which rows of the map `brands` carries — the stored order, from `offset`, `limit` rows, plus the customer’s own row and every tracked competitor’s whenever they fall outside them. `total` is every row on the map. Page on with `mapOffset` and `mapLimit`; `coreSize`, `untrackedCoreBrands` and `customerStanding` always describe the whole map, whatever page this is. See `item.summary.marketMap.brandsPage`.

item.answers[].askedIn — object

Field	Type	Description
`locationName`	`string`	The country or region the question was asked from, as Google names its markets.
`languageName`	`string`	The language the question was asked in, as Google names it.

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

Field	Type	Description
`url`	`string`	Address of the cited page.
`domain`	`string`	Domain of the cited page — the site Google cited.
`title`	`string`	Title of the cited page, as Google displayed it.

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

Field	Type	Description
`rank`	`number`	Position in this model’s answer — 1 means named first. For models that answer with a ranked list, this is the rank they gave. For Google AI Overviews, which answers in prose, it is the ORDER OF FIRST MENTION in `answerText`, computed by CompetLab — Google assigned no position, so never report it as a rank Google gave. 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`sentiment`	`string`	How warmly the model spoke about this brand in this answer. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. Values: `highly_recommended`, `recommended`, `mentioned`, `alternative`.
`mentionContext`	`string`	The role this brand played in the answer. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. Values: `direct_recommendation`, `comparison`, `alternative`, `niche_fit`.
`targetAudience`	`string`	Who the model said this brand is for. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`pricingSignal`	`string`	The price tier the model placed this brand in. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`features`	`array<string>`	Features the model highlighted for this brand (max 5). Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`differentiation`	`object`	How the model framed this brand’s differentiation. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. See `item.answers[].brands[].differentiation`.
`messaging`	`object`	The messaging the model associated with this brand. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.perplexity — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — not that it named nobody. Only `0` beside a non-zero `answersCounted` means it answered and named nobody.

item.providerStatus.google_ai_overviews — 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 `answersCounted` and `noAnswerShown` together. `answersCounted: 0` beside `noAnswerShown: 0` means we got no usable answer from this model — NEVER that it answered and named nobody — and those queries are listed in `unansweredQueries`. `answersCounted: 0` beside a non-zero `noAnswerShown` means the model was read and had nothing to show, which is not a failure.
`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. A `0` here does not by itself mean failure: read `noAnswerShown` beside it.
`noAnswerShown`	`number`	Queries to this model that were read and had no answer to show — the entries for this model in `noAnswerShown` on this response. Zero for every model but Google AI Overviews today. On a check published under the full-coverage gate, `answersCounted` plus this figure is the number of queries sent to it; on older checks a model that failed before answering anything recorded no slots at all, so the sum can fall short. None of these counts is ever a fraction of another.
`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 answer to count — 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`	ChatGPT metrics. Nested — see the Example tab.
`claude`	`object`	Claude metrics. Nested — see the Example tab.
`gemini`	`object`	Gemini metrics. Nested — see the Example tab.
`perplexity`	`object`	Perplexity metrics. Nested — see the Example tab.
`google_ai_overviews`	`object`	Google AI Overviews 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 where the model answered, but a model with `answersCounted: 0` under `perProvider` was read and had no answer to show on this check, and on a check published before that gate it could be an answer that never arrived.
`score`	`number`	0-100 position score for this prompt, averaged over the models whose answers this check counted — never over a fixed model count. Higher is better. 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. So it is not a rank and not a percentage of anything. 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. `mentionedBy` separates the two: non-empty means the models named them here. 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.summary.promptMarket.explanation — object

Field	Type	Description
`code`	`string`	Stable identifier for this sentence. Branch on it if you need to; never substitute your own wording for it. The project-level reading and a per-prompt reading carry DIFFERENT codes even where their `state` matches, so the two are not interchangeable and de-duplicating a list by code will not collapse them.
`text`	`string`	The sentence to report, in the words every CompetLab surface uses. Render it VERBATIM — do not paraphrase it, shorten it, or compose your own sentence from `state`. The wording is chosen to say only what this comparison can support, and a rewrite reliably says more than that. It carries no fraction and no percentage on purpose: this dimension’s headline metric is itself a count of answers, so a number inside this sentence gets read as a visibility rate. The counts are the sibling fields — put them beside the sentence, never inside it.

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

Field	Type	Description
`promptId`	`string`	Stable identifier for the prompt, minted once and kept for the life of that prompt — including when its wording is rewritten. It is the durable way to follow one prompt across checks. Note that the project endpoint returns prompt TEXTS and no ids, so lining a row up with a project’s current prompts means matching on `promptTextInProject` below.
`promptTextInProject`	`string`	The prompt’s wording as the project holds it now — which is also the wording every answer behind this reading was produced by, because answers produced by wording that has since been rewritten are excluded from it. Quote it so a reader can find the prompt in the project’s settings, and match on it to line this row up with the project endpoint’s prompt list. It will always match a current prompt; `promptId` is the durable handle if you need to follow one across edits.
`state`	`string`	This prompt’s own reading, on the same three-token scale as the project-level `state` and read in exactly the same way. Computed over the answers to THIS prompt alone, so it can differ from the project-level reading — which is the whole reason to look here. Values: `rivals_named_in_most_answers`, `rival_match_too_close_to_call`, `answers_and_rival_list_disagree`.
`explanation`	`object`	The sentence to report for this prompt, rendered verbatim like the project-level one. It is deliberately IDENTICAL for every prompt in the same state and never names the prompt — `promptId` and `promptTextInProject` do that. Say it once over a list of prompts rather than repeating a near-identical paragraph per row. Nested — see the Example tab.
`answersNamingAnyRival`	`number`	Answers to THIS prompt that named at least one company the account tracks. Membership, not volume: an answer that named four tracked competitors counts once, exactly like an answer that named one.
`answersMatchingCurrentPromptText`	`number`	Divide `answersNamingAnyRival` by THIS figure and nothing else. It is the universe that numerator is drawn from: answers to this prompt as its text stands TODAY. Two exclusions. A query that produced no usable answer is out entirely and is never counted as an answer that named nobody. An answer produced before the customer last edited this prompt’s text is also out, because it answers a question nobody is asking any more. Do not compare it to a figure on the market map: this row covers ONE prompt while the map pools every prompt, so it is a fraction of the map’s total by construction and that gap is not evidence of anything.

item.summary.marketMap.perEngine — object

Field	Type	Description
`openai`	`object`	ChatGPT coverage. Nested — see the Example tab.
`claude`	`object`	Claude coverage. Nested — see the Example tab.
`gemini`	`object`	Gemini coverage. Nested — see the Example tab.
`perplexity`	`object`	Perplexity coverage. Nested — see the Example tab.
`google_ai_overviews`	`object`	Google AI Overviews coverage. Nested — see the Example tab.

item.summary.marketMap.brands[] — each entry

Field	Type	Description
`answersNaming`	`number`	Answers in this view — the pooled map, or one AI model’s reading — that named the brand. Deduplicated within an answer — a brand named twice in one answer counts once — and matched on the domain, never on the brand’s wording.
`answersReceived`	`number`	The universe `answersNaming` is drawn from: usable answers in this view. Queries that produced no usable answer are out of it entirely. Quote it whenever you quote the share.
`presence`	`number`	`answersNaming / answersReceived × 100`, whole percent. THE ordering of every brand list here: how often a brand is named, never how high it sat. A share of answers analysed — never of queries sent, and never a probability. Always read with `presenceLow` / `presenceHigh` beside it.
`presenceLow`	`number`	Lower bound of a 95% interval on `presence`, in the same percent scale. Two brands whose ranges overlap are NOT ordered, whatever their rank says — never state that one is ahead of the other.
`presenceHigh`	`number`	Upper bound of the same interval. See `presenceLow`.
`zone`	`string`	Where this share sits once the sample’s uncertainty is taken into account. `named_in_a_quarter_or_more_of_answers`: the LOWER bound of the range is above 25% — these companies are the market as the AI models draw it. `named_in_under_a_tenth_of_answers`: the UPPER bound is below 10% — reachable only while `tailIsProvable` is true. `share_not_yet_separable`: the range straddles a line — a real company, sometimes named, that the evidence cannot yet place; this is the group that can still be moved. The token names a measured condition about a third party, never a verdict: say ‘named in under a tenth of answers’, never ‘irrelevant’ or ‘tail’. Thresholds are the same for every project. Values: `named_in_a_quarter_or_more_of_answers`, `named_in_under_a_tenth_of_answers`, `share_not_yet_separable`.
`domain`	`string`	Brand domain — the identity every count is matched on.
`name`	`string`	Brand name as the models most recently wrote it.
`isOwn`	`boolean`	Whether this is the customer’s own row. The customer’s row is ALWAYS on the map, at zero when no answer named them — that zero is a measured finding.
`rankByPresence`	`number \| null`	Rank by how often the brand is named: one plus the number of brands named more often. Ties SHARE a rank — several brands at the same share read as one rank, never as consecutive ones — so say ‘7th of 9 by how often it is named’, and never break a tie. Null at zero presence: a brand no answer in the window named has no place in this order, so say ‘not named in any answer’, never a rank. Only the customer’s own row can sit there, because every other row is on the map because an answer named it — and that row stays on the map, since its zero is measured. Nullable.
`perEngine`	`object`	This brand on each AI model that answered in the window. The pooled figures above are a vote across models — which AI models back a row — and a brand core to one model and a brand core to all of them look identical on the pooled figure, so read this before saying a brand is ‘core to the market’. A model absent here returned no usable answer in the window; a slice at zero is a model that answered and never named the brand. Nested — see the Example tab.
`endorsement`	`object \| null`	How warmly the models that describe brands recommend this one, on a scale from 21 to 100: the tone each answer gave it (highly recommended down to merely mentioned) and the role (a direct pick down to a fallback), weighted and averaged over the answers in the window that carried both, pooled the same way as `presence`. THE SCALE HAS A FLOOR, NOT A ZERO — a bare mention offered as a fallback still scores 21 — so read a low figure against 21, never against 0, and NEVER set it against `presence`: the two are different units, and a brand named in under 21% of answers sits on one side of any such comparison by arithmetic alone. There is no gap between them to report. It is the models’ own labels on their own answers, not an independent assessment of the brand. `null` means no answer in the window described the brand — named only by a model that describes nobody, or not named at all — never a low reading. Say ‘the models describe it as a fallback option’ from a figure near the floor, and ‘as a leading choice’ near 100; the state named on `customerStanding` is the comparison to make for the customer’s own row. Nullable. Nested — see the Example tab.
`pricePerception`	`object \| null`	Where the models that describe brands place this one’s price (shown in the app as ‘Price read’) — the tier they stated most often, with the mean’s position on a line from free (0) through budget, mid-range and premium to enterprise (100), pooled the same way as `presence`. What the models THINK it costs, never its price list: the scale has one thin independent witness and is not validated beyond the cheap end. `null` means no answer in the window stated a tier for it, never ‘free’. Report the tier word with its share of the answers, and say the models disagree when `tierAnswers` is under half of `answersRead`. Nullable. Nested — see the Example tab.

item.summary.marketMap.brandsPage — object

Field	Type	Description
`offset`	`number`	Rows skipped before this page, in stored order.
`limit`	`number`	Rows asked for. The page can hold more: rows its list always keeps — the customer’s own, where the list has one, and on the AI Visibility market map and history every tracked competitor’s — when they fall outside the page.
`total`	`number`	Rows in the whole list (after any filter), not on this page.
`hasMore`	`boolean`	Whether rows exist after this page. Ask for them with a higher offset.

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

Field	Type	Description
`axis`	`string`	The axis the model framed this brand as competing on. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them. 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.

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

Field	Type	Description
`keywords`	`array<string>`	Keywords the model associated with this brand (up to 5). Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.
`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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about 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. Absent when the model that produced this answer does not describe brands — Google AI Overviews names companies in prose and states nothing else about them.

Errors

Status	Code	Meaning
400	`invalid_parameters` · `invalid_run_id` · `invalid_check_id` · `bad_request` · `paging_requires_compact_view` · `paging_requires_summary` · `nothing_to_return`	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 how the market the AI models draw has moved

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

How the market the AI models draw has moved over a window: one row per company with how often it was recommended at the start of the window and now — a share of the answers pooled in each check’s window, with a 95% range and a zone — plus its rank by that share and its AI Visibility Score at both ends, the difference between the ends in each unit, and the models backing it. The project’s own company and every tracked competitor are always rows, however many there are, plus up to 3 companies the project does not track (the most recommended of the rest with a reading on the scope), all ordered by how often each is recommended on the latest map (ties are ties, so never break one). Each reading carries checksAnalysed, the checks its map pools: now is never the latest check alone. Two companies whose ranges overlap are not in a settled order whatever their shares say. 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. events carries what happened on the axis: the customer’s own standing changing zone and holding (the alerts the customer received — a standing is announced only once it has held for two checks), the cycles that produced no reading, and when the prompts were last edited (readings before that date answer different questions). provider reads one model’s own slice of every map; rank and score are then absent, since they exist only across every model. detail=series adds each company’s share check by check, downsampled to at most twelve points; omit it unless the shape between the ends matters. The window reads at most the newest 200 published checks — use dateFrom/dateTo for longer histories. Every figure here is a stored map’s own: a company a map does not carry is a measured zero of that map’s answers, and a model with no usable answer in a window is null, never zero.

Returns · { item }

Path parameters

Name	Type	Description
`projectId`	`string`	Project ID

Query parameters

Name	Type	Description
`dateFrom`	`string`	Start of the window (ISO-8601). Omit for the whole history: the newest 200 published checks, and the newest 200 cycles that produced no reading — on a longer history set both dates so the two cover one span.
`dateTo`	`string`	End of the window (ISO-8601).
`provider`	`string`	Read one AI model’s own slice of every map instead of the pooled map. Omit for every model at once. Under one model `rank` and `score` are null on every reading and `enginesBacking` is left off the rows — they exist only across every model; never read that as ‘no model named them’. Values: `openai`, `claude`, `gemini`, `perplexity`, `google_ai_overviews`.
`detail`	`string`	`series` adds each company’s share check by check, downsampled to at most 12 points spread evenly over the window. Omit it unless the shape between the two ends matters: the rows already carry the reading now, the reading at the start and the difference. Values: `series`.

Request


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

Response 200 OK

Example


{
  "item": {
    "window": {
      "from": "2026-08-12T09:30:00.000Z",
      "to": "2026-08-30T09:30:00.000Z",
      "checks": 16,
      "answersReceived": 60,
      "checksAnalysed": 5,
      "providersAsked": [
        "openai",
        "claude",
        "gemini",
        "perplexity",
        "google_ai_overviews"
      ]
    },
    "scope": "all",
    "companies": [
      {
        "name": "Acme",
        "domain": "acme.com",
        "isOwn": false,
        "isTracked": true,
        "enginesBacking": [
          "openai",
          "claude"
        ],
        "now": {
          "date": "2026-08-30T09:30:00.000Z",
          "checkId": "507f1f77bcf86cd799439012",
          "checksAnalysed": 5,
          "presence": {
            "answersNaming": 24,
            "answersReceived": 60,
            "presence": 40,
            "presenceLow": 28,
            "presenceHigh": 53,
            "zone": "named_in_a_quarter_or_more_of_answers"
          },
          "rank": 3,
          "score": 41
        },
        "start": {
          "date": "2026-08-30T09:30:00.000Z",
          "checkId": "507f1f77bcf86cd799439012",
          "checksAnalysed": 5,
          "presence": {
            "answersNaming": 24,
            "answersReceived": 60,
            "presence": 40,
            "presenceLow": 28,
            "presenceHigh": 53,
            "zone": "named_in_a_quarter_or_more_of_answers"
          },
          "rank": 3,
          "score": 41
        },
        "presenceChange": 12,
        "presenceChangeSeparable": true,
        "rankChange": 2,
        "scoreChange": 9,
        "series": [
          {
            "date": "2026-08-20T09:30:00.000Z",
            "checksAnalysed": 5,
            "presence": 27,
            "presenceLow": 17,
            "presenceHigh": 40
          }
        ]
      }
    ],
    "events": {
      "standingChanges": [
        {
          "date": "2026-08-26T09:30:00.000Z",
          "from": "share_not_yet_separable",
          "to": "named_in_a_quarter_or_more_of_answers"
        }
      ],
      "incompleteCycles": [
        {
          "date": "2026-03-14T02:00:00.000Z",
          "reason": "incomplete_coverage",
          "measuredAnswers": 8,
          "expectedAnswers": 12,
          "absentAnswers": 1
        }
      ],
      "promptsLastChangedAt": "2026-08-16T14:00:00.000Z"
    }
  }
}

Fields

item — object

Field	Type	Description
`window`	`object`	The window the readings were taken over. See `item.window`.
`scope`	`string`	Every AI model at once (`all`), or the one asked for with `provider`. Under one model the readings are that model’s own slices of each map, and rank and score are absent.
`companies`	`array<object>`	One row per company, in the order of how often each is recommended on the latest map — ties are ties. The project’s own company and every tracked competitor are always here, however many there are, plus up to 3 companies the project does not track — the most recommended of the rest. A company with no measured reading on this scope in the window is left out, and never takes one of those 3 places. See `item.companies[]`.
`events`	`object`	What happened on the time axis, as facts — the consumer writes the sentence. See `item.events`.

item.window — object

Field	Type	Description
`from`	`string \| null`	When the first published check in the window completed (ISO-8601); null when the window holds none. Nullable.
`to`	`string \| null`	When the last published check in the window completed (ISO-8601); null when the window holds none. Nullable.
`checks`	`number`	Published checks in the window — the checks the readings were taken at.
`answersReceived`	`number \| null`	Usable answers pooled on the latest map on this scope — the denominator of every `now` reading. Null under a `provider` filter for a model with no usable answer in the latest window. Nullable.
`checksAnalysed`	`number`	Published checks pooled into the latest map — every reading is over a window of up to this many checks, never one check alone.
`providersAsked`	`array<string>`	The models the latest check asked, as recorded on it. A check keeps the model set it ran with.

item.companies[] — each entry

Field	Type	Description
`name`	`string`	The company’s name as the latest map in the window labels it — a label, not an identity; match companies on `domain`.
`domain`	`string`	The company’s domain — its identity across every check and every surface.
`isOwn`	`boolean`	True on the project’s own company — the row every other row is read against.
`isTracked`	`boolean`	True when the project tracks this domain as a competitor today. False means it is not on today’s tracked list — on an earlier reading that can be a competitor tracked then and dropped since. The customer’s own row is false.
`enginesBacking`	`array<string>`	The models that recommended the company at least once in the latest check’s window, in a fixed order. A company named by one model and one named by all of them read the same on the pooled share, so read this before saying a company is named across the market rather than by one model. An empty list means no model named the company on the latest map — a measured absence. ABSENT under a `provider` filter: one model’s slice cannot say which models back a company, so the key is left off rather than emptied.
`now`	`object`	The latest measured reading in the window. See `item.companies[].now`.
`start`	`object \| null`	The earliest measured reading in the window, when it is a different check from `now`. Null when the window holds a single measured reading — there is no movement to report then, and every `*Change` field is null with it. Nullable. See `item.companies[].start`.
`presenceChange`	`number \| null`	`now.presence.presence` minus `start.presence.presence`, in points of share. Positive means recommended more often now. Null without a `start`. Nullable.
`presenceChangeSeparable`	`boolean \| null`	Whether the two readings’ ranges separate — `now`’s 95% interval sits wholly above or wholly below `start`’s. True: the change is a settled move and may be reported as one. False: the ranges overlap, so `presenceChange` is the difference between two readings and never ‘rose’ or ‘fell’ — say the share now and at the start, and that the ranges overlap. Null without a `start`. Nullable.
`rankChange`	`number \| null`	`start.rank` minus `now.rank` — places moved, positive means the company climbed. Null without a rank on both ends — a company named in no answer at either end has no rank there, so it has no places to have moved — and always null under a `provider` filter. Nullable.
`scoreChange`	`number \| null`	`now.score` minus `start.score`. Null without a score on both ends, and always null under a `provider` filter. Nullable.
`series`	`array<object>`	Only with `detail=series`: the company’s share check by check, oldest first, at most 12 points spread evenly over the window with the first and the last always included. Read the ends from `start` and `now`; this is for the shape between them. See `item.companies[].series[]`.

item.events — object

Field	Type	Description
`standingChanges`	`array<object>`	The customer’s own standing on the market map moving to a different zone and holding there — the alerts the customer received, as dated marks. A standing is announced only once it has held for two consecutive published checks, so a one-check blip never appears here. Empty when none in the window. See `item.events.standingChanges[]`.
`incompleteCycles`	`array<object>`	Monitoring cycles inside the window that produced no reading, because at least one query they asked could not be read. Reported so a gap between two readings is distinguishable from a period when nothing was scheduled. The newest 200 in the window, oldest first — the same end the readings are cut from, so on a long history set `dateFrom`/`dateTo` to keep both on one span. Empty for a window with none — an empty array never means “we know there were no gaps”. See `item.events.incompleteCycles[]`.
`promptsLastChangedAt`	`string \| null`	When the project’s prompts were last edited (ISO-8601), or null when never. Readings before that date are answers to different questions; do not read a move across it as the market moving. Nullable.

item.companies[].now — object

Field	Type	Description
`date`	`string`	When the published check this reading is from completed (ISO-8601).
`checkId`	`string`	That check’s id — pass it to the check-detail route to read the answers behind the reading.
`checksAnalysed`	`number`	How many published checks that check’s map pools — the window this reading’s answers come from. Checks, never days. `now` is never the latest check alone.
`presence`	`object`	How often the company was recommended in that check’s window, with its range and zone. See `item.companies[].now.presence`.
`rank`	`number \| null`	The company’s rank by how often it was recommended on that check’s map: one plus the companies recommended more often, ties sharing a rank. Null where no answer in that check’s window named the company — off the map, or on it at a measured zero — and null under a `provider` filter, since a rank exists only across every model. Without a `provider` filter the null is a measured absence — say ‘not named’, never ‘not measured’. Nullable.
`score`	`number \| null`	The company’s AI Visibility Score on that check (0-100). 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. 0 where no counted answer named the company in its top 5, whether never named or named only below the scoring positions: a measured 0, for the customer and every other company alike. Read presence beside it to tell the two apart. null where that check’s map carries the company but its rows hold no score for it, and under a `provider` filter, since the score is one figure across every model. Nullable.

item.companies[].start — object

Field	Type	Description
`date`	`string`	When the published check this reading is from completed (ISO-8601).
`checkId`	`string`	That check’s id — pass it to the check-detail route to read the answers behind the reading.
`checksAnalysed`	`number`	How many published checks that check’s map pools — the window this reading’s answers come from. Checks, never days. `now` is never the latest check alone.
`presence`	`object`	How often the company was recommended in that check’s window, with its range and zone. See `item.companies[].start.presence`.
`rank`	`number \| null`	The company’s rank by how often it was recommended on that check’s map: one plus the companies recommended more often, ties sharing a rank. Null where no answer in that check’s window named the company — off the map, or on it at a measured zero — and null under a `provider` filter, since a rank exists only across every model. Without a `provider` filter the null is a measured absence — say ‘not named’, never ‘not measured’. Nullable.
`score`	`number \| null`	The company’s AI Visibility Score on that check (0-100). 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. 0 where no counted answer named the company in its top 5, whether never named or named only below the scoring positions: a measured 0, for the customer and every other company alike. Read presence beside it to tell the two apart. null where that check’s map carries the company but its rows hold no score for it, and under a `provider` filter, since the score is one figure across every model. Nullable.

item.companies[].series[] — each entry

Field	Type	Description
`date`	`string`	When the published check completed (ISO-8601).
`checksAnalysed`	`number`	How many published checks that check’s map pools — the window the point’s answers come from. Checks, never days.
`presence`	`number \| null`	The share of answers recommending the company in that check’s window, in whole percent — or null where this scope was not measured on that check (the model returned no usable answer in the window). Null is a break in the line, never a zero; a measured zero ships as 0. Nullable.
`presenceLow`	`number \| null`	The lower bound of the 95% interval on that share; null with `presence`. Nullable.
`presenceHigh`	`number \| null`	The upper bound of the same interval; null with `presence`. Nullable.

item.events.standingChanges[] — each entry

Field	Type	Description
`date`	`string`	When the change was announced (ISO-8601) — the second check the new standing held on.
`from`	`string \| null`	The customer’s zone before the change; null when the customer was on no map before — a measured absence, not a failed measurement. Values: `named_in_a_quarter_or_more_of_answers`, `named_in_under_a_tenth_of_answers`, `share_not_yet_separable`. Nullable.
`to`	`string`	The customer’s zone after the change — the state that held. Values: `named_in_a_quarter_or_more_of_answers`, `named_in_under_a_tenth_of_answers`, `share_not_yet_separable`.

item.events.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 reading. `incomplete_coverage` — at least one query it asked could not be read — no usable answer came back from it. A query the model was read for and had no answer to show does not count against coverage. Values: `incomplete_coverage`.
`measuredAnswers`	`number`	Answers that came back usable in this cycle. Not a visibility figure — a cycle can be fully covered and score zero.
`expectedAnswers`	`number`	Answers the cycle asked for: every AI model it queried, against every prompt it ran — read the number from this field; do not recompute it from today’s model count, which is not necessarily that cycle’s. `expectedAnswers` − `measuredAnswers` is the uncounted total, and it is two facts added together: queries that could not be read, plus queries the model was read for that had no answer to show (`absentAnswers`). Subtract `absentAnswers` from that shortfall to get the number of queries that could not be read; report the two apart, never the total as answers that failed to arrive.
`absentAnswers`	`number`	Queries in this cycle the model was read for and had no answer to show — today, prompts for which Google’s results page carried no AI Overview. They sit inside `expectedAnswers` − `measuredAnswers` without being failures: that shortfall minus this figure is the number of queries that could not be read.

item.companies[].now.presence — object

Field	Type	Description
`answersNaming`	`number`	Answers in the check’s window that named the company — the numerator. Every prompt asks for a recommendation, so a company named in an answer is one the model recommended. Deduplicated within an answer, matched on the domain.
`answersReceived`	`number`	Usable answers pooled in that window on this scope — the denominator, and the universe of every figure on this reading. Never the number of queries sent.
`presence`	`number`	`answersNaming` / `answersReceived` × 100, rounded to a whole percent. A share of answers, never a probability.
`presenceLow`	`number`	The lower bound of a 95% interval on that share, in whole percent. Two companies whose intervals overlap are NOT in a settled order, whatever the shares say.
`presenceHigh`	`number`	The upper bound of the same interval, in whole percent.
`zone`	`string`	Where the share sits once the sample’s uncertainty is allowed for — a measured condition, never a verdict. `named_in_a_quarter_or_more_of_answers`: the lower bound is above 25%, the company is part of the market as the models draw it. `named_in_under_a_tenth_of_answers`: the upper bound is below 10%. `share_not_yet_separable`: the interval straddles a line — recommended sometimes, but too few answers to say whether that is often or rarely. Report the condition in those words; never ‘irrelevant’, ‘tail’ or ‘core’ as a judgement. Values: `named_in_a_quarter_or_more_of_answers`, `named_in_under_a_tenth_of_answers`, `share_not_yet_separable`.

item.companies[].start.presence — object

Field	Type	Description
`answersNaming`	`number`	Answers in the check’s window that named the company — the numerator. Every prompt asks for a recommendation, so a company named in an answer is one the model recommended. Deduplicated within an answer, matched on the domain.
`answersReceived`	`number`	Usable answers pooled in that window on this scope — the denominator, and the universe of every figure on this reading. Never the number of queries sent.
`presence`	`number`	`answersNaming` / `answersReceived` × 100, rounded to a whole percent. A share of answers, never a probability.
`presenceLow`	`number`	The lower bound of a 95% interval on that share, in whole percent. Two companies whose intervals overlap are NOT in a settled order, whatever the shares say.
`presenceHigh`	`number`	The upper bound of the same interval, in whole percent.
`zone`	`string`	Where the share sits once the sample’s uncertainty is allowed for — a measured condition, never a verdict. `named_in_a_quarter_or_more_of_answers`: the lower bound is above 25%, the company is part of the market as the models draw it. `named_in_under_a_tenth_of_answers`: the upper bound is below 10%. `share_not_yet_separable`: the interval straddles a line — recommended sometimes, but too few answers to say whether that is often or rarely. Report the condition in those words; never ‘irrelevant’, ‘tail’ or ‘core’ as a judgement. Values: `named_in_a_quarter_or_more_of_answers`, `named_in_under_a_tenth_of_answers`, `share_not_yet_separable`.

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
  }
}