AI Competitors API endpoint

POST /v1/compareAbout AI Competitors

Compare one brand with up to 10 competitors in AI answers: side-by-side rankings per model plus a co-mention graph of which brands appear together.

Overview

Like /v1/rankings but for one primary brand against a competitor set, with a coMentions graph: for each pair of brands, how many model answers name both, surfacing who AI frames you alongside.

Need a weekly or monthly comparison history? Save this input with the Tracker API.

Reading the metrics

Rates count usable answers only (2 of 3 = 66.7%); no usable answers means unavailable, not 0%. Position is mention order, not search ranking.

Reference

POST/v1/compare

$0.01 to $0.06 / model · billed per model queried, so all 5 models = $0.20. Pass models to query fewer.

Parameters

querystringrequired

The query to compare the brand and competitors on.

brandstringrequired

Your brand — ranked alongside the competitors.

competitorsstring[]required

Competitor brand/domain names (up to 10) to rank against your brand.

modelsenum[]optional

AI surfaces to query, each billed separately; pass a subset when the user names surfaces or wants a lower cost. Omit for the defaults (chatgpt, perplexity, gemini); fullSweep queries all five. google_ai_overview accepts queries up to 700 characters, the others 2000.

Values:chatgptclaudeperplexitygeminigoogle_ai_overview

fullSweepbooleanoptional

Query all five AI surfaces (adds claude and google_ai_overview) for full cross-surface coverage, at a higher cost. Ignored when models is given.

Parameter	Type	Description
queryrequired	string	The query to compare the brand and competitors on.
brandrequired	string	Your brand — ranked alongside the competitors.
competitorsrequired	string[]	Competitor brand/domain names (up to 10) to rank against your brand.
modelsoptional	enum[]	AI surfaces to query, each billed separately; pass a subset when the user names surfaces or wants a lower cost. Omit for the defaults (chatgpt, perplexity, gemini); fullSweep queries all five. google_ai_overview accepts queries up to 700 characters, the others 2000. Values:chatgptclaudeperplexitygeminigoogle_ai_overview
fullSweepoptional	boolean	Query all five AI surfaces (adds claude and google_ai_overview) for full cross-surface coverage, at a higher cost. Ignored when models is given.

Request

curl https://www.cite42.dev/api/v1/compare \
  -X POST \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fullSweep":true,"query":"best startup CRM","brand":"Acme CRM","competitors":["Rival CRM","Legacy CRM"]}'

Response

{
  "query": "best startup CRM",
  "brand": "Acme CRM",
  "rankings": [
    {
      "competitor": "Acme CRM",
      "mentionRate": 0.6,
      "avgPosition": 2,
      "byModel": {
        "chatgpt": 2,
        "claude": 2,
        "perplexity": 2,
        "gemini": null,
        "google_ai_overview": null
      }
    },
    {
      "competitor": "Rival CRM",
      "mentionRate": 0.8,
      "avgPosition": 1,
      "byModel": {
        "chatgpt": 1,
        "claude": 1,
        "perplexity": 1,
        "gemini": 1,
        "google_ai_overview": null
      }
    }
  ],
  "coMentions": [
    {
      "a": "Acme CRM",
      "b": "Rival CRM",
      "count": 2
    }
  ],
  "measurement": {
    "methodologyVersion": "2026-09-28-v1:aio-v2",
    "surfaces": [
      {
        "model": "chatgpt",
        "provider": "OpenAI",
        "access": "official-api",
        "webSearch": "auto",
        "status": "complete"
      },
      {
        "model": "claude",
        "provider": "Anthropic",
        "access": "official-api",
        "webSearch": "auto",
        "status": "complete"
      },
      {
        "model": "perplexity",
        "provider": "Perplexity",
        "access": "native-search",
        "webSearch": "always",
        "status": "complete"
      },
      {
        "model": "gemini",
        "provider": "Google Gemini",
        "access": "official-api",
        "webSearch": "auto",
        "status": "complete"
      },
      {
        "model": "google_ai_overview",
        "provider": "Google AI Overviews",
        "access": "live-serp",
        "webSearch": "always",
        "status": "complete"
      }
    ]
  },
  "metrics": {
    "definitionVersion": "2026-09-23-v1",
    "checkedAnswers": 5,
    "requestedAnswers": 5,
    "excludedAnswers": 0,
    "note": "A descriptive sample, not a market-wide score. Small samples can swing sharply. Failed, empty and incomplete answers are excluded. Cached observations may be reused. A mention is not an endorsement; position is first-mention order, not a Google ranking.",
    "mentions": [
      {
        "brand": "Acme CRM",
        "numerator": 3,
        "denominator": 5,
        "percentage": 60,
        "label": "60% — 3 of 5 checked answers"
      },
      {
        "brand": "Rival CRM",
        "numerator": 4,
        "denominator": 5,
        "percentage": 80,
        "label": "80% — 4 of 5 checked answers"
      }
    ]
  },
  "requestId": "…",
  "billing": {
    "cost": {
      "microCredits": 20000,
      "usd": "0.20"
    },
    "balance": {
      "microCredits": 1336000,
      "usd": "13.36"
    }
  }
}