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

# Get Performance Snapshot

> Get performance snapshots and GEO scores for your brand

Get a comprehensive overview of your brand's visibility in AI-generated responses. Includes mention rates, source citations, sentiment scores, share of voice, and breakdowns by topic and competitor.

<Note>
  This endpoint returns aggregated metrics. See [Competitor](/api-reference/entities#competitor) and [Source](/api-reference/entities#source) for entity structures used in `topCompetitors` and `topSources`.
</Note>

### Key Formulas

Understanding how metrics are calculated is essential for reproducing results:

| Metric             | Formula                               | Details                                                                                                                                                                    |
| ------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Mention Rate**   | `mentionCount / mentionTotal × 100`   | `mentionCount` = responses where your brand (SELF) is mentioned. `mentionTotal` = responses with **at least one SELF or DIRECT competitor mention** (not total responses). |
| **Coverage**       | `mentionCount / responsesTotal × 100` | Percentage of **all** monitored responses mentioning your brand. Unlike Mention Rate, uses total responses as denominator.                                                 |
| **Source Rate**    | `sourceCount / sourceTotal × 100`     | `sourceCount` = responses citing your domain (SELF). `sourceTotal` = responses with **at least one SELF or DIRECT source citation** (not total responses).                 |
| **Share of Voice** | `sovSelf / sovTotal × 100`            | `sovSelf` = distinct SELF mention count. `sovTotal` = distinct SELF + DIRECT mention count. **INDIRECT mentions are excluded.**                                            |

<Warning>
  **Common mistake:** Using total responses as the denominator for Mention Rate, or including INDIRECT competitor mentions in the Share of Voice denominator. The API returns `sovSelf` and `sovTotal` so you can verify the calculation.
</Warning>

## Get Performance Snapshot

<ParamField header="Authorization" type="string" required>
  Bearer token. Example: `Bearer qw-api-xxx`
</ParamField>

```http theme={null}
GET /api/v1/brands/{brandId}/performance
```

### Path Parameters

<ParamField path="brandId" type="string" required>
  The unique identifier of the brand
</ParamField>

### Query Parameters

<ParamField query="period" type="number">
  Number of days to include in the snapshot. If not specified, returns all data.
</ParamField>

<ParamField query="startDate" type="string">
  Start date (ISO 8601 format). Overrides `period` if provided with `endDate`
</ParamField>

<ParamField query="endDate" type="string">
  End date (ISO 8601 format). Overrides `period` if provided with `startDate`
</ParamField>

<ParamField query="provider" type="string">
  Filter by AI provider. Supports comma-separated multi-select (e.g., `chatgpt,claude`).
</ParamField>

<ParamField query="topic" type="string">
  Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="tag" type="string">
  Filter by tag ID. Supports comma-separated multi-select (e.g., `id1,id2`).
</ParamField>

<ParamField query="type" type="string">
  Filter by prompt type: `TOFU`, `MOFU`, `BOFU`
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful
</ResponseField>

<ResponseField name="brand" type="object">
  <Expandable title="Brand info">
    <ResponseField name="id" type="string">Brand ID</ResponseField>
    <ResponseField name="name" type="string">Brand name</ResponseField>
    <ResponseField name="domain" type="string">Primary domain</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="period" type="object">
  <Expandable title="Period info">
    <ResponseField name="start" type="string">Start date (ISO 8601)</ResponseField>
    <ResponseField name="end" type="string">End date (ISO 8601)</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="methodology" type="object">
  <Expandable title="Methodology details">
    <ResponseField name="promptsCount" type="number">Total prompts analyzed</ResponseField>
    <ResponseField name="providersCount" type="number">Number of AI providers</ResponseField>
    <ResponseField name="providers" type="array">List of provider IDs (e.g., `chatgpt`, `perplexity`)</ResponseField>
    <ResponseField name="responsesTotal" type="number">Total AI responses generated</ResponseField>
    <ResponseField name="responsesWithMentions" type="number">Responses containing brand mentions</ResponseField>
    <ResponseField name="responsesWithSources" type="number">Responses citing sources</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="scores" type="object">
  <Expandable title="Performance scores">
    <ResponseField name="mentionRate" type="number">Brand mention rate (%)</ResponseField>
    <ResponseField name="mentionCount" type="number">Number of responses where your brand (SELF) is mentioned</ResponseField>
    <ResponseField name="mentionTotal" type="number">Number of responses containing **at least one SELF or DIRECT competitor mention**. This is the denominator for `mentionRate` — it is NOT the total number of responses. INDIRECT mentions are excluded.</ResponseField>
    <ResponseField name="coverage" type="number">Brand coverage (%). Percentage of all monitored responses where your brand is mentioned. Formula: `mentionCount / responsesTotal × 100`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate (%)</ResponseField>
    <ResponseField name="sourceCount" type="number">Number of source citations</ResponseField>
    <ResponseField name="sourceTotal" type="number">Number of responses containing **at least one SELF or DIRECT source citation**. This is the denominator for `sourceRate` — it is NOT the total number of responses. INDIRECT sources are excluded.</ResponseField>
    <ResponseField name="sourcePages" type="number">Number of unique URLs from your domain (SELF) cited as sources across all AI responses.</ResponseField>
    <ResponseField name="sentiment" type="number">Average sentiment score (0-100)</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice (%). Formula: SELF mentions / (SELF + DIRECT mentions) × 100. INDIRECT mentions are excluded.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="topCompetitors" type="array">
  Top competitors by mention count
</ResponseField>

<ResponseField name="topSources" type="array">
  Top sources by citation count
</ResponseField>

<ResponseField name="byTopic" type="array">
  <Expandable title="Topic breakdown object">
    <ResponseField name="id" type="string">Topic ID</ResponseField>
    <ResponseField name="topic" type="string">Topic name</ResponseField>
    <ResponseField name="score" type="number">Composite score (0-100). Formula: `mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2`.</ResponseField>
    <ResponseField name="mentionRate" type="number">Mention rate for this topic (%). Formula: `selfMentionAnswers / responsesWithMentions × 100` where `responsesWithMentions` counts answers in this topic with at least one SELF or DIRECT competitor mention. Same denominator semantic as the top-level `scores.mentionRate`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate for this topic (%). Formula: `selfSourceAnswers / responsesWithSources × 100` where `responsesWithSources` counts answers in this topic with at least one SELF or DIRECT source citation. Same denominator semantic as the top-level `scores.sourceRate` (INDIRECT excluded).</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice for this topic (%). Formula: SELF mentions in topic / (SELF + DIRECT mentions in topic) × 100.</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average sentiment score for brand mentions in this topic (null if no mentions)</ResponseField>
    <ResponseField name="promptsCount" type="number">Number of distinct prompts in this topic</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="byTag" type="array">
  <Expandable title="Tag breakdown object">
    <ResponseField name="id" type="string">Tag ID</ResponseField>
    <ResponseField name="name" type="string">Tag name</ResponseField>
    <ResponseField name="score" type="number">Composite score (0-100). Formula: `mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2`.</ResponseField>
    <ResponseField name="mentionRate" type="number">Mention rate for this tag (%). Formula: `selfMentionAnswers / responsesWithMentions × 100` where `responsesWithMentions` counts answers in this tag with at least one SELF or DIRECT competitor mention. Same denominator semantic as the top-level `scores.mentionRate`.</ResponseField>
    <ResponseField name="sourceRate" type="number">Source citation rate for this tag (%). Formula: `selfSourceAnswers / responsesWithSources × 100` where `responsesWithSources` counts answers in this tag with at least one SELF or DIRECT source citation. Same denominator semantic as the top-level `scores.sourceRate` (INDIRECT excluded).</ResponseField>
    <ResponseField name="shareOfVoice" type="number">Share of voice for this tag (%). Formula: SELF mentions in tag / (SELF + DIRECT mentions in tag) × 100.</ResponseField>
    <ResponseField name="avgSentiment" type="number">Average sentiment score for brand mentions in this tag (null if no mentions)</ResponseField>
    <ResponseField name="promptsCount" type="number">Number of distinct prompts in this tag</ResponseField>
  </Expandable>
</ResponseField>

### Example Request

```bash theme={null}
curl -X GET "https://www.qwairy.co/api/v1/brands/cm1234567890abcdef/performance?period=30" \
  -H "Authorization: Bearer qw-api-your-token-here"
```

### Example Response

```json theme={null}
{
  "success": true,
  "brand": {
    "id": "cm1234567890abcdef",
    "name": "My Brand",
    "domain": "mybrand.com"
  },
  "period": {
    "start": "2024-12-01",
    "end": "2024-12-31"
  },
  "methodology": {
    "promptsCount": 156,
    "providersCount": 2,
    "providers": ["chatgpt", "perplexity"],
    "responsesTotal": 312,
    "responsesWithMentions": 230,
    "responsesWithSources": 184
  },
  "scores": {
    "mentionRate": 45.2,
    "mentionCount": 104,
    "mentionTotal": 230,
    "coverage": 33.33,
    "sourceRate": 23.9,
    "sourceCount": 44,
    "sourceTotal": 184,
    "sourcePages": 27,
    "sentiment": 78.1,
    "shareOfVoice": 8.13
  },
  "topCompetitors": [
    {
      "id": "cmp1",
      "name": "Competitor A",
      "relationship": "DIRECT",
      "mentions": 111,
      "avgPosition": 2.3,
      "avgSentiment": 75.2
    }
  ],
  "topSources": [
    {
      "id": "src1",
      "domain": "industry-news.com",
      "mentions": 102,
      "avgPosition": 3.1,
      "isSelf": false
    }
  ],
  "byTopic": [
    {
      "id": "topic1",
      "topic": "Product Reviews",
      "score": 68,
      "mentionRate": 67.50,
      "sourceRate": 28.00,
      "shareOfVoice": 9.44,
      "avgSentiment": 76.3,
      "promptsCount": 12
    }
  ],
  "byTag": [
    {
      "id": "tag1",
      "name": "comparison",
      "score": 72,
      "mentionRate": 55.00,
      "sourceRate": 30.00,
      "shareOfVoice": 10.25,
      "avgSentiment": 81.5,
      "promptsCount": 8
    }
  ]
}
```

### Error Responses

| Status | Code                | Description                           |
| ------ | ------------------- | ------------------------------------- |
| 400    | `INVALID_PARAMETER` | Invalid query parameter               |
| 401    | `INVALID_TOKEN`     | Authentication failed                 |
| 404    | `BRAND_NOT_FOUND`   | Brand doesn't exist or not accessible |