Competitor evolution
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/competitors/{competitorId}/evolution \
--header 'Authorization: Bearer <token>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/competitors/{competitorId}/evolution"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/competitors/{competitorId}/evolution', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));Competitors
Competitor evolution
Track how a competitor’s metrics change over time.
GET
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
competitors
/
{competitorId}
/
evolution
Competitor evolution
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/competitors/{competitorId}/evolution \
--header 'Authorization: Bearer <token>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/competitors/{competitorId}/evolution"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://www.qwairy.co/api/v1/brands/{brandId}/competitors/{competitorId}/evolution', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));Returns daily mention occurrences, SELF-and-DIRECT Share of Voice, average position, and average mention sentiment for one competitor.
Path parameters
string
required
The unique identifier of the brand
string
required
The unique identifier of the competitor
Query parameters
number
Number of days to include. 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.string
Filter by AI provider. Supports comma-separated multi-select (e.g.,
chatgpt,claude).string
Filter by topic ID. Supports comma-separated multi-select (e.g.,
id1,id2).string
Filter by tag ID. Supports comma-separated multi-select (e.g.,
id1,id2).Synthetic request
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/competitors/COMPETITOR_ID/evolution?period=7" \
-H "Authorization: Bearer $QWAIRY_API_TOKEN"
Synthetic response
{
"success": true,
"competitor": {
"id": "competitor_01",
"name": "Rival Labs",
"relationship": "DIRECT"
},
"evolution": [
{
"date": "2026-07-01",
"mentions": 5,
"shareOfVoice": 7.2,
"avgPosition": 2.3,
"avgSentiment": 76.5
},
{
"date": "2026-07-02",
"mentions": 8,
"shareOfVoice": 8.5,
"avgPosition": 2.1,
"avgSentiment": 78.2
}
]
}
Errors
| Status | Code | Description |
|---|---|---|
| 401 | gateway error | Missing or invalid API token |
| 404 | BRAND_NOT_FOUND | Brand doesn’t exist or not accessible |
| 404 | COMPETITOR_NOT_FOUND | Competitor doesn’t exist |
| 429 | gateway error | Rate limit exceeded; honor Retry-After |
avgSentiment uses the 0 to 100 mention-sentiment scale and can be null. See Rate limits for retry behavior.