> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genrank.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Mentions: Brand Visibility Data in the API

> Reference for the mentions array in GenRank API responses — position, text snippets, entity annotations, visibility scores, and perceived qualities.

The `mentions` array is the core of every GenRank API response. Each element in the array represents a single detected occurrence of your brand in a ChatGPT response — capturing where it appeared, what was said, how visible it was, what qualities were attributed to it, and which competitors appeared in the same response.

A single prompt execution can produce multiple mention objects if your brand is referenced more than once in the ChatGPT response. In most cases there will be one or two mention objects per response, but complex or longer responses may contain more.

## Mention object fields

<ResponseField name="mentions" type="array" required>
  An array of mention objects, each representing a detected brand mention within the ChatGPT response for the tracked prompt. An empty array indicates the brand was not mentioned in the response.

  <Expandable title="mention object properties">
    <ResponseField name="position" type="integer" required>
      The position of this mention within the response — where in the sequence of brand references it falls. A value of `1` indicates this is the first mention of the brand in the response. Lower position values generally correlate with stronger prominence.

      Example: `1`
    </ResponseField>

    <ResponseField name="text_snippet" type="string" required>
      An excerpt from the ChatGPT response containing the brand mention. This is the actual text as returned by ChatGPT — not paraphrased or summarized. Use this field to understand the context and framing of the mention.

      Example: `"GenRank is one of the top tools to track brand visibility in ChatGPT."`
    </ResponseField>

    <ResponseField name="annotations" type="array" required>
      An array of entity annotation objects identifying specific named entities within the `text_snippet`. Each annotation marks the exact character position of the entity and classifies its type.

      <Expandable title="annotation object properties">
        <ResponseField name="entity" type="string" required>
          The name of the detected entity exactly as it appears in the text.

          Example: `"GenRank"`
        </ResponseField>

        <ResponseField name="position_start" type="integer" required>
          The zero-indexed character position in `text_snippet` where the entity begins.

          Example: `0`
        </ResponseField>

        <ResponseField name="position_end" type="integer" required>
          The zero-indexed character position in `text_snippet` where the entity ends (exclusive). You can use `text_snippet[position_start:position_end]` to extract the entity string directly.

          Example: `7`
        </ResponseField>

        <ResponseField name="type" type="string" required>
          The entity type classification. For brand tracking, this value is typically `"brand"`. Additional types may be present depending on your configured outputs.

          Example: `"brand"`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="visibility_percent" type="number" required>
      A score between `0` and `100` representing how visible the brand is within this response. The score accounts for factors including mention position, response length, and prominence of the mention relative to other brands. A higher score indicates stronger, more prominent visibility.

      Example: `72.5`
    </ResponseField>

    <ResponseField name="perceived_brand_qualities" type="array" required>
      An array of strings representing the qualities or attributes ChatGPT associated with your brand in this response. These are derived from the language used around your brand mention — adjectives, descriptors, and implied characteristics. Use this field to understand how AI currently frames your brand.

      Example: `["accurate", "easy to use", "SEO-focused"]`
    </ResponseField>

    <ResponseField name="competitors" type="array" required>
      An array of strings listing other brand names that appeared in the same ChatGPT response as your brand. This field tells you which competitors co-occurred in the same answer — useful for competitive benchmarking and share-of-voice analysis. See [Competitors](/api/competitors) for more detail on how to use this data.

      Example: `["SEranking", "ChatGPT Tracker"]`
    </ResponseField>
  </Expandable>
</ResponseField>

## Sample mention object

The following shows a complete mention object as it appears in a GenRank API response.

```json theme={null}
{
  "position": 1,
  "text_snippet": "GenRank is one of the top tools to track brand visibility in ChatGPT.",
  "annotations": [
    {
      "entity": "GenRank",
      "position_start": 0,
      "position_end": 7,
      "type": "brand"
    }
  ],
  "visibility_percent": 72.5,
  "perceived_brand_qualities": [
    "accurate",
    "easy to use",
    "SEO-focused"
  ],
  "competitors": ["SEranking", "ChatGPT Tracker"]
}
```

## Full response with mentions

```json theme={null}
{
  "brand": "GenRank",
  "domain": "genrank.io",
  "geo": "US",
  "query": "best chatgpt brand tracker",
  "mentions": [
    {
      "position": 1,
      "text_snippet": "GenRank is one of the top tools to track brand visibility in ChatGPT.",
      "annotations": [
        {
          "entity": "GenRank",
          "position_start": 0,
          "position_end": 7,
          "type": "brand"
        }
      ],
      "visibility_percent": 72.5,
      "perceived_brand_qualities": [
        "accurate",
        "easy to use",
        "SEO-focused"
      ],
      "competitors": ["SEranking", "ChatGPT Tracker"]
    }
  ],
  "last_checked": "2025-09-26T10:00:00Z"
}
```

## Interpreting mention data

### Using `position` to assess prominence

A lower `position` value means your brand was mentioned earlier in the response. ChatGPT tends to introduce the most recommended or well-known options first, so a position of `1` is meaningful signal — it suggests your brand is being presented as a leading option for that prompt, not an afterthought.

Tracking position changes over time, particularly after publishing new content or earning coverage, helps you understand whether your optimization efforts are improving your placement within responses.

### Reading `text_snippet` for context

The `text_snippet` field gives you the actual language ChatGPT used when mentioning your brand. This is the most direct signal for understanding framing. A snippet like "GenRank is one of the top tools to track brand visibility in ChatGPT" tells you not just that you were mentioned, but that you were positioned as a leading tool and associated with ChatGPT visibility tracking specifically.

Compare snippets across prompts to understand whether your brand is framed consistently or differently depending on the question context.

### Interpreting `visibility_percent`

Visibility percent is a composite score — it does not measure a single thing but combines several factors into a single number. Use it as a directional signal for trend monitoring rather than as an absolute measure of prominence. A score of 72.5 indicates strong, prominent visibility. Scores below 30 generally reflect brief or peripheral mentions.

<Tip>
  Track `visibility_percent` over time across your full prompt set to identify trends. A rising average suggests your brand is becoming more central to AI-generated answers in your category. A sustained drop may signal that a competitor has increased its presence.
</Tip>

### Using `perceived_brand_qualities` for positioning analysis

The qualities in this array are extracted from the language patterns around your brand mention in the ChatGPT response. They reflect how AI currently frames your brand — which may or may not align with how you intend to be positioned.

If you see qualities that do not match your intended positioning (for example, if you want to be known for enterprise scalability but AI describes you as a small business tool), that gap is useful input for your content and GEO strategy.

### Handling empty `mentions` arrays

If the `mentions` array is empty, your brand was not detected in the ChatGPT response for that prompt. This is a prompt gap — a query where you have no AI visibility. Empty mention arrays are valuable data points for competitive analysis: check the `competitors` field in responses from related prompts to see which brands are being recommended in your place.

```python theme={null}
# Filter for prompt gaps (no brand mentions)
gaps = [r for r in responses if len(r["mentions"]) == 0]

print(f"Found {len(gaps)} prompt gaps out of {len(responses)} tracked prompts")
```