Competitors

get_competitor_analysis

Every tracked question classified (winning, losing, open race, invisible…), with citation split, per-engine win rate and the trend.

readReads only. Annotated read-only, so a client can call it without asking.

Plan: Grow and above
Rate cost: 3 units
REST: GET /projects/{project_id}/competitor-analysis

Try asking

“Break our questions down into winning, losing and open races.”

get_competitor_analysis

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_competitor_analysis",
    "arguments": {
      "project_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  }
}

structuredContent

{
  "content": [
    {
      "type": "text",
      "text": "…the same JSON, as text…"
    }
  ],
  "structuredContent": {
    "coverage": {
      "analyzable": 31,
      "total": 40,
      "analyzable_pct": 77.5
    },
    "states": [
      {
        "label": "winning",
        "count": 8
      },
      {
        "label": "losing",
        "count": 14
      },
      {
        "label": "open_race",
        "count": 6
      },
      {
        "label": "invisible",
        "count": 9
      },
      {
        "label": "insufficient_evidence",
        "count": 3
      }
    ],
    "citation": {
      "customer": 18.4,
      "competitor": 33.7,
      "third_party": 47.9,
      "total_citations": 217,
      "confidence": "high"
    },
    "model_split": [
      {
        "engine": "ChatGPT",
        "win_rate": 28.6
      },
      {
        "engine": "Perplexity",
        "win_rate": 41.2
      }
    ],
    "prompts": [
      {
        "prompt_id": "0e9a7c55-2b3d-4c1e-8f6a-9d0b1c2e3f4a",
        "prompt_ref": 12,
        "prompt_text": "best invoicing software for freelancers in India",
        "state": "losing",
        "priority": "high",
        "top_rival": "Northwind Billing",
        "confidence": "high"
      }
    ],
    "trend": [
      {
        "date": "2026-09-20",
        "states": [
          {
            "label": "winning",
            "count": 8
          },
          {
            "label": "losing",
            "count": 14
          }
        ]
      }
    ]
  },
  "isError": false
}

Arguments

Passed as the tool call's arguments.

project_idstringrequired

The project to read, from list_projects.

Result

The same object as Get competitor analysis, returned as structured output.

coverageobject

How many prompts have enough evidence to classify.

+Show child attributes

analyzableinteger

Prompts with enough evidence.

totalinteger

Prompts classified.

analyzable_pctnumber

analyzable as a share of total, 0–100.

statesobject[]

Prompts per state. States with no prompts are left out.

+Show child attributes

labelstring

State.

Values:winninglosingopen_racemodel_contestedvolatileuncontestedinvisibleinsufficient_evidence

countinteger

How many.

citationobject

Whose pages the contested answers cite.

+Show child attributes

customernumber

Share citing the brand's domains, 0–100.

competitornumber

Share citing competitors' domains, 0–100.

third_partynumber

Share citing anyone else, 0–100.

total_citationsinteger

Citations counted.

confidencestring

high from 20 citations, medium from 8.

Values:highmediumlow

model_splitobject[]

Head-to-head win rate per engine.

+Show child attributes

enginestring

Engine name.

Values:ChatGPTPerplexityGeminiCopilotAI OverviewsClaude

win_ratenumber

Share of shared answers naming the brand first, 0–100.

promptsobject[]

Every classified prompt.

+Show child attributes

prompt_idstring

Prompt id.

prompt_refinteger

The prompt's short number.

prompt_textstring

The prompt.

statestring

winning / losing: named first in at least 60% of shared answers, or beaten that often. open_race: no one reaches 60%. model_contested: engines disagree. volatile: the winner keeps changing. uncontested: no rival appears often enough. invisible: the brand is never named. insufficient_evidence: fewer than 5 answers.

Values:winninglosingopen_racemodel_contestedvolatileuncontestedinvisibleinsufficient_evidence

prioritystring

high for buying questions (best, vs, pricing, alternatives), low for navigational ones.

Values:highmediumlow

top_rivalstringnullable

The competitor beating the brand here, if any.

confidencestring

high from 20 answers, medium from 8.

Values:highmediumlow

trendobject[]

Prompts per state over time, oldest first.

+Show child attributes

datestring

Day, as YYYY-MM-DD.

statesobject[]

Every state and its count, zeros included.

+Show child attributes

labelstring

State.

Values:winninglosingopen_racemodel_contestedvolatileuncontestedinvisibleinsufficient_evidence

countinteger

How many.

Errors

404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
403 forbidden	The workspace or the member the key acts as can't do this in the dashboard either — for example a project with competitive analysis switched off.
401 unauthorized	No key was sent, or the key is unknown, revoked or expired, or the member who created it has left the workspace or been deactivated.
402 plan_required	The workspace's plan doesn't include API access. It's included on Grow, Scale and Custom.
403 workspace_not_approved	The workspace is still waiting for approval, or wasn't approved.
429 rate_limited	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header, then retry.

Every code, and what to retry, is in Errors.

Failures arrive as a tool error — isError: true with code: message as text. See Using the tools.