Skip to main content
Monitor how your brand and competitors are mentioned in AI responses. Competitors have three relationship types: SELF (your brand), DIRECT (direct competitors), and INDIRECT (indirect competitors). The list and evolution endpoints return only SELF and DIRECT by default. Share of Voice is calculated using only SELF and DIRECT mentions.
See Entities for the complete Competitor object structure.

​
List Competitors

​
Authorization
string
required
Bearer token. Example: Bearer qw-api-xxx
GET /api/v1/brands/{brandId}/competitors

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand

​
Query Parameters

​
period
number
Number of days to include. If not specified, returns all data.
​
startDate
string
Start date (ISO 8601 format)
​
endDate
string
End date (ISO 8601 format)
​
provider
string
Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).
​
topic
string
Filter by topic ID. Supports comma-separated multi-select (e.g., id1,id2).
​
tag
string
Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).
​
type
string
Filter by prompt type: TOFU, MOFU, BOFU
​
limit
number
default:"50"
Maximum number of results to return (max: 100)
​
offset
number
default:"0"
Number of results to skip for pagination
​
sort
string
default:"mentions"
Field to sort by: mentions, position, sentiment, shareOfVoice, name
​
order
string
default:"desc"
Sort order: asc or desc

​
Response

Returns competitors with relationship SELF (your brand) and DIRECT (direct competitors). INDIRECT competitors are not included in this endpoint.
​
success
boolean
Indicates if the request was successful
​
pagination
object
​
competitors
array

​
Example Request

curl -X GET "https://www.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
    },
    {
      "id": "cmp2",
      "name": "Competitor A",
      "domain": "competitor-a.com",
      "relationship": "DIRECT",
      "totalMentions": 111,
      "shareOfVoice": 8.73,
      "avgPosition": 1.8,
      "avgSentiment": 75.2
    }
  ]
}

​
Get Competitor Details

GET /api/v1/brands/{brandId}/competitors/{competitorId}

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand
​
competitorId
string
required
The unique identifier of the competitor

​
Query Parameters

​
period
number
Number of days to include. If not specified, returns all data.
​
startDate
string
Start date (ISO 8601 format)
​
endDate
string
End date (ISO 8601 format)
​
provider
string
Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).
​
topic
string
Filter by topic ID. Supports comma-separated multi-select (e.g., id1,id2).
​
tag
string
Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).

​
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,
    "byProvider": [
      { "provider": "ChatGPT", "mentions": 62, "avgPosition": 2.0 },
      { "provider": "Perplexity", "mentions": 42, "avgPosition": 2.3 }
    ],
    "byTopic": [
      { "topic": "Product Reviews", "mentions": 45 },
      { "topic": "Comparisons", "mentions": 38 }
    ]
  }
}

​
Get Competitor Evolution

Track how a competitor’s metrics change over time. 
GET /api/v1/brands/{brandId}/competitors/{competitorId}/evolution

​
Path Parameters

​
brandId
string
required
The unique identifier of the brand
​
competitorId
string
required
The unique identifier of the competitor

​
Query Parameters

​
period
number
Number of days to include. If not specified, returns all data.
​
startDate
string
Start date (ISO 8601 format)
​
endDate
string
End date (ISO 8601 format)
​
provider
string
Filter by AI provider. Supports comma-separated multi-select (e.g., chatgpt,claude).
​
topic
string
Filter by topic ID. Supports comma-separated multi-select (e.g., id1,id2).
​
tag
string
Filter by tag ID. Supports comma-separated multi-select (e.g., id1,id2).

​
Example Request

curl -X GET "https://www.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
    },
    {
      "date": "2024-12-02",
      "mentions": 8,
      "shareOfVoice": 8.5,
      "avgPosition": 2.1,
      "avgSentiment": 78.2
    }
  ]
}

​
Error Responses

StatusCodeDescription
401INVALID_TOKENAuthentication failed
404BRAND_NOT_FOUNDBrand doesn’t exist or not accessible
404COMPETITOR_NOT_FOUNDCompetitor doesn’t exist