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 with daily mention occurrences, Share of Voice, average position, and average mention sentiment.
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
Query parameters
Start date in
YYYY-MM-DD. Provide it with endDate; a lone boundary is currently ignored. Choose either period or the complete date pair.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.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.