List competitors
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/competitors \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/competitors"
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}/competitors', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"pagination": {
"total": 123,
"count": 123,
"limit": 123,
"offset": 123
},
"competitors": [
{
"id": "<string>",
"name": "<string>",
"domain": "<string>",
"relationship": "<string>",
"totalMentions": 123,
"shareOfVoice": 123,
"avgPosition": 123,
"avgSentiment": {}
}
]
}Competitors
List competitors
Track competitor mentions, share of voice, and positioning.
GET
https://www.qwairy.co
/
api
/
v1
/
brands
/
{brandId}
/
competitors
List competitors
curl --request GET \
--url https://www.qwairy.co/api/v1/brands/{brandId}/competitors \
--header 'Authorization: <authorization>'import requests
url = "https://www.qwairy.co/api/v1/brands/{brandId}/competitors"
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}/competitors', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"success": true,
"pagination": {
"total": 123,
"count": 123,
"limit": 123,
"offset": 123
},
"competitors": [
{
"id": "<string>",
"name": "<string>",
"domain": "<string>",
"relationship": "<string>",
"totalMentions": 123,
"shareOfVoice": 123,
"avgPosition": 123,
"avgSentiment": {}
}
]
}Lists competitor domains and mention metrics for the selected scope. The default relationship set is
See Rate limits for retry behavior.
SELF,DIRECT; include INDIRECT explicitly when needed. On this endpoint, Share of Voice uses mention occurrences from the selected relationship set.
See Entities for the complete Competitor object structure.
string
required
Bearer token. Example:
Bearer qw-api-xxxPath parameters
string
required
The unique identifier of the brand
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).string
Filter by prompt type:
TOFU, MOFU, BOFUstring
default:"SELF,DIRECT"
Filter by relationship type. Supports comma-separated multi-select:
SELF, DIRECT, INDIRECT. Default: SELF,DIRECT.number
default:"50"
Maximum number of results to return (max: 100)
number
default:"0"
Number of results to skip for pagination
string
default:"mentions"
Field to sort by:
mentions, position, sentiment, shareOfVoice, namestring
default:"desc"
Sort order:
asc or descResponse
Returns competitors from the requested relationship filter.INDIRECT is excluded only by the default filter.
boolean
Indicates if the request was successful
object
array
Show Competitor object
Show Competitor object
string
Competitor ID
string
Competitor name
string
Competitor domain
string
SELF, DIRECT, or INDIRECT, subject to the relationship filternumber
Total mentions count
number
This row’s mention occurrences divided by all mention occurrences in the selected relationship set
number
Average position in responses
number | null
Average mention sentiment on a 0 to 100 scale, or
nullSynthetic request
curl "https://www.qwairy.co/api/v1/brands/YOUR_BRAND_ID/competitors?limit=10&offset=0" \
-H "Authorization: Bearer $QWAIRY_API_TOKEN"
Synthetic response
{
"success": true,
"pagination": {
"total": 10,
"count": 2,
"limit": 10,
"offset": 0
},
"competitors": [
{
"id": "competitor_self",
"name": "Acme Analytics",
"domain": "acme.example",
"relationship": "SELF",
"totalMentions": 104,
"shareOfVoice": 8.13,
"avgPosition": 2.1,
"avgSentiment": 78.1
},
{
"id": "competitor_01",
"name": "Rival Labs",
"domain": "rival.example",
"relationship": "DIRECT",
"totalMentions": 111,
"shareOfVoice": 8.73,
"avgPosition": 1.8,
"avgSentiment": 75.2
}
]
}
Errors
| Status | Meaning |
|---|---|
400 | Invalid query parameter or relationship filter |
401 | Missing or invalid API token |
404 | Brand not found or inaccessible |
429 | Rate limit exceeded; honor Retry-After |

