Get Performance Snapshot
curl --request GET \
--url https://api.example.com/api/v1/brands/{brandId}/performance \
--header 'Authorization: <authorization>'import requests
url = "https://api.example.com/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://api.example.com/api/v1/brands/{brandId}/performance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/brands/{brandId}/performance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/brands/{brandId}/performance"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/brands/{brandId}/performance")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/brands/{brandId}/performance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
}
]
}Cockpit
Get Performance Snapshot
Get performance snapshots and GEO scores for your brand
GET
/
api
/
v1
/
brands
/
{brandId}
/
performance
Get Performance Snapshot
curl --request GET \
--url https://api.example.com/api/v1/brands/{brandId}/performance \
--header 'Authorization: <authorization>'import requests
url = "https://api.example.com/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://api.example.com/api/v1/brands/{brandId}/performance', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/v1/brands/{brandId}/performance",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: <authorization>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/v1/brands/{brandId}/performance"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "<authorization>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/brands/{brandId}/performance")
.header("Authorization", "<authorization>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/v1/brands/{brandId}/performance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'
response = http.request(request)
puts response.read_body{
"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
}
]
}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:| 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. |
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
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 (ISO 8601 format). Overrides
period if provided with endDatestring
End date (ISO 8601 format). Overrides
period if provided with startDatestring
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
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 source citations
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 sentiment score (0-100)
number
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
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": {
"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 |
⌘I

