List Competitors

curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/competitors \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.example.com/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://api.example.com/api/v1/brands/{brandId}/competitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/brands/{brandId}/competitors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/brands/{brandId}/competitors"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/brands/{brandId}/competitors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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": 123
    }
  ]
}

GET

api

brands

{brandId}

competitors

List Competitors

curl --request GET \
  --url https://api.example.com/api/v1/brands/{brandId}/competitors \
  --header 'Authorization: <authorization>'

import requests

url = "https://api.example.com/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://api.example.com/api/v1/brands/{brandId}/competitors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/brands/{brandId}/competitors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/brands/{brandId}/competitors"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/brands/{brandId}/competitors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

{
  "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": 123
    }
  ]
}

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.

string

required

Bearer token. Example: Bearer qw-api-xxx

Path 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 (ISO 8601 format)

string

End date (ISO 8601 format)

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, BOFU

string

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, name

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 by default.

boolean

Indicates if the request was successful

object

Show Pagination info

number

Total number of competitors matching filters

number

Number of competitors in this response

number

Maximum items per page

number

Number of items skipped

array

Show Competitor object

string

Competitor ID

string

Competitor name

string

Competitor domain

string

SELF (your brand) or DIRECT (competitor)

number

Total mentions count

Share of voice (%)

number

Average position in responses

number

Average sentiment score (0-100)

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
    }
  ]
}

Getting Started

Setup

Cockpit

Monitor

Analyze

Act

Optimize

Agencies

Webhooks

Guides

List Competitors

Path Parameters

Query Parameters

Response

Example Request

Example Response

​Path Parameters

​Query Parameters

​Response

​Example Request

​Example Response

Path Parameters

Query Parameters

Response

Example Request

Example Response