Monitor how your brand and competitors are mentioned in AI responses. Competitors are categorized as SELF (your brand) or DIRECT (competitors). Track mention counts, average position, sentiment, and share of voice over time.
See Entities for the complete Competitor object structure. List Competitors Bearer token. Example: Bearer qw-api-xxx
GET /api/v1/brands/{brandId}/competitors
Path Parameters The unique identifier of the brand
Query Parameters Number of days to include
Start date (ISO 8601 format)
End date (ISO 8601 format)
Filter by AI provider: chatgpt, perplexity, claude, gemini, etc.
Filter by prompt type: TOFU, MOFU, BOFU
Maximum number of results to return (max: 100)
Number of results to skip for pagination
Field to sort by: mentions, position, sentiment, relevance, shareOfVoice, name
Response Returns all competitors with relationship SELF (your brand) and DIRECT (competitors).
Indicates if the request was successful
Total number of competitors matching filters
Number of competitors in this response
SELF (your brand) or DIRECT (competitor)
Average position in responses
Average sentiment score (0-100)
Average relevance score (0-100)
Example Request curl -X GET "https://qwairy.co/api/v1/brands/cm1234567890abcdef/competitors?limit=10&offset=0" \ -H "Authorization: Bearer qw-api-your-token-here"
Example Response { "success" : true , "pagination" : { "total" : 10 , "count" : 2 , "limit" : 10 , "offset" : 0 }, "competitors" : [ { "id" : "cmp1" , "name" : "My Brand" , "domain" : "mybrand.com" , "relationship" : "SELF" , "totalMentions" : 104 , "shareOfVoice" : 8.13 , "avgPosition" : 2.1 , "avgSentiment" : 78.1 , "avgRelevance" : 72.5 }, { "id" : "cmp2" , "name" : "Competitor A" , "domain" : "competitor-a.com" , "relationship" : "DIRECT" , "totalMentions" : 111 , "shareOfVoice" : 8.73 , "avgPosition" : 1.8 , "avgSentiment" : 75.2 , "avgRelevance" : 68.3 } ] }
Get Competitor Details GET /api/v1/brands/{brandId}/competitors/{competitorId}
Path Parameters The unique identifier of the brand
The unique identifier of the competitor
Query Parameters Number of days to include
Start date (ISO 8601 format)
End date (ISO 8601 format)
Response Returns detailed competitor information with breakdowns by provider and topic.
Example Response { "success" : true , "competitor" : { "id" : "cmp1" , "name" : "My Brand" , "domain" : "mybrand.com" , "relationship" : "SELF" , "totalMentions" : 104 , "shareOfVoice" : 8.13 , "avgPosition" : 2.1 , "avgSentiment" : 78.1 , "avgRelevance" : 72.5 , "byProvider" : [ { "provider" : "ChatGPT" , "mentions" : 62 , "avgPosition" : 2.0 }, { "provider" : "Perplexity" , "mentions" : 42 , "avgPosition" : 2.3 } ], "byTopic" : [ { "topic" : "Product Reviews" , "mentions" : 45 , "shareOfVoice" : 9.44 }, { "topic" : "Comparisons" , "mentions" : 38 , "shareOfVoice" : 12.06 } ] } }
Get Competitor Evolution Track how a competitor’s metrics change over time.
GET /api/v1/brands/{brandId}/competitors/{competitorId}/evolution
Path Parameters The unique identifier of the brand
The unique identifier of the competitor
Query Parameters Number of days to include
Start date (ISO 8601 format)
End date (ISO 8601 format)
Example Request curl -X GET "https://qwairy.co/api/v1/brands/cm1234567890abcdef/competitors/cmp1/evolution?period=7" \ -H "Authorization: Bearer qw-api-your-token-here"
Example Response { "success" : true , "competitor" : { "id" : "cmp1" , "name" : "My Brand" , "relationship" : "SELF" }, "evolution" : [ { "date" : "2024-12-01" , "mentions" : 5 , "shareOfVoice" : 7.2 , "avgPosition" : 2.3 , "avgSentiment" : 76.5 , "avgRelevance" : 71.0 }, { "date" : "2024-12-02" , "mentions" : 8 , "shareOfVoice" : 8.5 , "avgPosition" : 2.1 , "avgSentiment" : 78.2 , "avgRelevance" : 73.1 } ] }
Error Responses Status Code Description 401 INVALID_TOKENAuthentication failed 404 BRAND_NOT_FOUNDBrand doesn’t exist or not accessible 404 COMPETITOR_NOT_FOUNDCompetitor doesn’t exist
