GET /sites/competitors

Returns competitor visibility analysis showing how often competitors appear across questions.

Request

Endpoint

https://knowatoa.com/api/v2/sites/competitors

Query Parameters

Parameter	Type	Required	Description
site_id	string	Yes	Site prefix ID (e.g., tpc_abc123)
api_key	string	Yes	Your API authentication key
flat	string	No	Set to "true" for flat JSON format
format	string	No	Set to "csv" for CSV export
start_date	string	No	Period start (YYYY-MM-DD). With end_date, returns period metrics instead of the latest refresh. See Period Comparison
end_date	string	No	Period end (YYYY-MM-DD), inclusive
compare_start	string	No	Comparison period start. Defaults to the equal-length period before start_date
compare_end	string	No	Comparison period end, inclusive

Response

Nested JSON Format

{
  "site": {
    "id": "tpc_abc123",
    "name": "Example Site",
    "external_id": "example.com"
  },
  "refresh_date": "2025-01-15",
  "competitors": [
    {
      "competitor_name": "Competitor A",
      "mentions": 45,
      "questions": 30,
      "percentage": 66.7
    }
  ]
}

Response Fields

Field	Type	Description
competitor_name	string	Name of competitor
mentions	integer	Total number of mentions
questions	integer	Number of unique questions mentioned in
percentage	float	Percentage of total questions

Period Comparison

Returns period, compare_to, and competitors: the site (is_target: true) and each competitor with site_id, name, url, and metrics: mention_rate, mentions, samples, average_position, sentiment_score, sentiment_evaluated, positive_count, neutral_count, negative_count. Mention rate uses the same denominator for every brand (completed AI responses for the site’s questions).

Notes

Returns empty array if no competitors configured
Competitors sorted by mention count (descending)
Percentages rounded to 1 decimal place