Get performance snapshot
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/performance \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/performance"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/performance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"brand": {
"id": "<string>",
"name": "<string>",
"domain": "<string>"
},
"period": {
"start": "<string>",
"end": "<string>"
},
"methodology": {
"promptsCount": 123,
"providersCount": 123,
"providers": [
{}
],
"responsesTotal": 123,
"responsesWithMentions": 123,
"responsesWithSources": 123
},
"scores": {
"mentionRate": 123,
"mentionCount": 123,
"mentionTotal": 123,
"coverage": 123,
"sourceRate": 123,
"sourceCount": 123,
"sourceTotal": 123,
"sourcePages": 123,
"sentiment": 123,
"shareOfVoice": 123
},
"topCompetitors": [
{}
],
"topSources": [
{}
],
"byTopic": [
{
"id": "<string>",
"topic": "<string>",
"score": 123,
"mentionRate": 123,
"sourceRate": 123,
"shareOfVoice": 123,
"avgSentiment": 123,
"promptsCount": 123
}
],
"byTag": [
{
"id": "<string>",
"name": "<string>",
"score": 123,
"mentionRate": 123,
"sourceRate": 123,
"shareOfVoice": 123,
"avgSentiment": 123,
"promptsCount": 123
}
]
}Performance
Get performance snapshot
Read response-level mention, citation, sentiment, and Share of Voice metrics for a brand.
GET
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
performance
Get performance snapshot
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/performance \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/performance"
headers = {"Authorization": "<authorization>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: '<authorization>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/performance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"brand": {
"id": "<string>",
"name": "<string>",
"domain": "<string>"
},
"period": {
"start": "<string>",
"end": "<string>"
},
"methodology": {
"promptsCount": 123,
"providersCount": 123,
"providers": [
{}
],
"responsesTotal": 123,
"responsesWithMentions": 123,
"responsesWithSources": 123
},
"scores": {
"mentionRate": 123,
"mentionCount": 123,
"mentionTotal": 123,
"coverage": 123,
"sourceRate": 123,
"sourceCount": 123,
"sourceTotal": 123,
"sourcePages": 123,
"sentiment": 123,
"shareOfVoice": 123
},
"topCompetitors": [
{}
],
"topSources": [
{}
],
"byTopic": [
{
"id": "<string>",
"topic": "<string>",
"score": 123,
"mentionRate": 123,
"sourceRate": 123,
"shareOfVoice": 123,
"avgSentiment": 123,
"promptsCount": 123
}
],
"byTag": [
{
"id": "<string>",
"name": "<string>",
"score": 123,
"mentionRate": 123,
"sourceRate": 123,
"shareOfVoice": 123,
"avgSentiment": 123,
"promptsCount": 123
}
]
}Returns response-level metrics for the selected answer scope, plus topic, tag, competitor, and source breakdowns.
See Rate limits for retry behavior.
This endpoint returns aggregated metrics. See Competitor and Source for entity structures used in
topCompetitors and topSources.Metric formulas
Understanding how metrics are calculated is essential for reproducing results:| Metric | Formula | Details |
|---|---|---|
| Mention Rate | mentionCount / mentionTotal × 100 | mentionCount is the number of answers with a SELF mention. mentionTotal is the number of answers with at least one SELF or DIRECT mention. |
| Coverage | mentionCount / responsesTotal × 100 | Answer-level coverage: answers with a SELF mention divided by every answer in the selected scope. This is not prompt-level Coverage. |
| Source Rate | sourceCount / sourceTotal × 100 | sourceCount is the number of answers with a SELF citation. sourceTotal is the number of answers with at least one SELF or DIRECT citation. |
| Share of Voice | sovSelf / sovTotal × 100 | SELF mention occurrences divided by SELF and DIRECT mention occurrences. INDIRECT mentions are excluded. |
Mention Rate and Coverage have different denominators. The response exposes
mentionCount, mentionTotal, and responsesTotal; it does not expose sovSelf or sovTotal.string
required
Bearer token. Example:
Bearer qw-api-xxxGET /api/v1/brands/{brandId}/performance
Path parameters
string
required
The unique identifier of the brand
Query parameters
number
Number of days to include in the snapshot. If not specified, returns all data.
string
Start date in
YYYY-MM-DD. Provide it with endDate; a lone boundary is currently ignored. Choose either period or the complete date pair.string
End date in
YYYY-MM-DD. Provide it with startDate; a lone boundary is currently ignored. Do not combine the complete date pair with period.Use one date mode per request. Combining
period with a complete custom date pair can make the applied filter diverge from the returned period metadata.string
Filter by AI provider. Supports comma-separated multi-select (e.g.,
chatgpt,claude).string
Filter by topic ID (keywordId). Supports comma-separated multi-select (e.g.,
id1,id2).string
Filter by tag ID. Supports comma-separated multi-select (e.g.,
id1,id2).string
Filter by prompt type:
TOFU, MOFU, BOFUResponse
boolean
Indicates if the request was successful
object
Show Methodology details
Show Methodology details
object
Show Performance scores
Show Performance scores
number
Brand mention rate (%)
number
Number of responses where your brand (SELF) is mentioned
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.number
Brand coverage (%). Percentage of all monitored responses where your brand is mentioned. Formula:
mentionCount / responsesTotal × 100.number
Source citation rate (%)
number
Number of distinct answers containing a SELF citation
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.number
Number of unique URLs from your domain (SELF) cited as sources across all AI responses.
number
Average SELF mention sentiment on a 0 to 100 scale;
0 is also returned when no scored SELF mention existsnumber
Share of voice (%). Formula: SELF mentions / (SELF + DIRECT mentions) × 100. INDIRECT mentions are excluded.
array
Top competitors by mention count
array
Top sources by citation count
array
Show Topic breakdown object
Show Topic breakdown object
string
Topic ID
string
Topic name
number
Composite score (0-100). Formula:
mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2.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.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).number
Share of voice for this topic (%). Formula: SELF mentions in topic / (SELF + DIRECT mentions in topic) × 100.
number
Average sentiment score for brand mentions in this topic (null if no mentions)
number
Number of distinct prompts in this topic
array
Show Tag breakdown object
Show Tag breakdown object
string
Tag ID
string
Tag name
number
Composite score (0-100). Formula:
mentionRate × 0.5 + sourceRate × 0.3 + shareOfVoice × 0.2.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.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).number
Share of voice for this tag (%). Formula: SELF mentions in tag / (SELF + DIRECT mentions in tag) × 100.
number
Average sentiment score for brand mentions in this tag (null if no mentions)
number
Number of distinct prompts in this tag
Synthetic request
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/performance?period=30" \
-H "Authorization: Bearer $QWAIRY_API_TOKEN"
Synthetic response
{
"success": true,
"brand": {
"id": "brand_01",
"name": "Acme Analytics",
"domain": "acme.example"
},
"period": {
"start": "2026-07-01",
"end": "2026-07-31"
},
"methodology": {
"promptsCount": 156,
"providersCount": 2,
"providers": ["openai", "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": "competitor_01",
"name": "Rival Labs",
"relationship": "DIRECT",
"mentions": 111,
"avgPosition": 2.3,
"avgSentiment": 75.2
}
],
"topSources": [
{
"id": "source_01",
"domain": "publisher.example",
"mentions": 102,
"avgPosition": 3.1,
"isSelf": false
}
],
"byTopic": [
{
"id": "topic_01",
"topic": "Data exports",
"score": 68,
"mentionRate": 67.50,
"sourceRate": 28.00,
"shareOfVoice": 9.44,
"avgSentiment": 76.3,
"promptsCount": 12
}
],
"byTag": [
{
"id": "tag_01",
"name": "comparison",
"score": 72,
"mentionRate": 55.00,
"sourceRate": 30.00,
"shareOfVoice": 10.25,
"avgSentiment": 81.5,
"promptsCount": 8
}
]
}
Errors
| Status | Code | Description |
|---|---|---|
| 400 | INVALID_PARAMETER | Invalid query parameter |
| 401 | gateway error | Missing or invalid API token |
| 404 | BRAND_NOT_FOUND | Brand doesn’t exist or not accessible |
| 429 | gateway error | Rate limit exceeded; honor Retry-After |

