Skip to main content
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.
This endpoint returns aggregated metrics. See Competitor and Source for entity structures used in topCompetitors and topSources.

​
Key Formulas

Understanding how metrics are calculated is essential for reproducing results:
MetricFormulaDetails
Mention RatementionCount / mentionTotal × 100mentionCount = responses where your brand (SELF) is mentioned. mentionTotal = responses with at least one SELF or DIRECT competitor mention (not total responses).
Source RatesourceCount / sourceTotal × 100sourceCount = responses citing your domain (SELF). sourceTotal = responses with at least one SELF or DIRECT source citation (not total responses).
Share of VoicesovSelf / sovTotal × 100sovSelf = distinct SELF mention count. sovTotal = distinct SELF + DIRECT mention count. INDIRECT mentions are excluded.
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.

​
Get Performance Snapshot

​
Authorization
string
required
Bearer token. Example: Bearer qw-api-xxx
GET /api/v1/brands/{brandId}/performance

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand

​
Query Parameters

​
period
number
Number of days to include in the snapshot. If not specified, returns all data.
​
startDate
string
Start date (ISO 8601 format). Overrides period if provided with endDate
​
endDate
string
End date (ISO 8601 format). Overrides period if provided with startDate
​
provider
string
Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).
​
topic
string
Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g., id1,id2).
​
tag
string
Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).
​
type
string
Filter by prompt type: TOFU, MOFU, BOFU

​
Response

​
success
boolean
Indicates if the request was successful
​
brand
object
​
period
object
​
methodology
object
​
scores
object
​
topCompetitors
array
Top competitors by mention count
​
topSources
array
Top sources by citation count
​
byTopic
array
Performance breakdown by topic
​
byTag
array
Performance breakdown by tag

​
Example Request

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

​
Example Response

{
  "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": {
    "global": 62,
    "mentionRate": 45.2,
    "mentionCount": 104,
    "mentionTotal": 230,
    "sourceRate": 23.9,
    "sourceCount": 44,
    "sourceTotal": 184,
    "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
    }
  ],
  "byTag": [
    {
      "id": "tag1",
      "name": "comparison",
      "score": 72,
      "mentionRate": 55.00,
      "sourceRate": 30.00,
      "shareOfVoice": 10.25
    }
  ]
}

​
Error Responses

StatusCodeDescription
400INVALID_PARAMETERInvalid query parameter
401INVALID_TOKENAuthentication failed
404BRAND_NOT_FOUNDBrand doesn’t exist or not accessible