Competitors

get_competitor_standings

Each tracked rival's visibility and the brand's head-to-head win rate against it.

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

Plan: Grow and above
Rate cost: 1 unit
REST: GET /projects/{project_id}/competitors

Try asking

“Who beats us most often in AI answers?”

get_competitor_standings

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

structuredContent

{
  "content": [
    {
      "type": "text",
      "text": "…the same JSON, as text…"
    }
  ],
  "structuredContent": {
    "rivals": [
      {
        "name": "Northwind Billing",
        "visibility": 62.5,
        "win_rate": 30,
        "co_appearances": 10
      },
      {
        "name": "Contoso Books",
        "visibility": 45,
        "win_rate": 55.6,
        "co_appearances": 9
      },
      {
        "name": "Fabrikam Pay",
        "visibility": 12.5,
        "win_rate": null,
        "co_appearances": 3
      }
    ],
    "total_probes": 40,
    "min_co_appearances": 8
  },
  "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 standings, returned as structured output.

rivalsobject[]

Tracked competitors, biggest threat (lowest head-to-head win rate) first; rows without a win rate last.

+Show child attributes

namestring

Competitor.

visibilitynumber

Share of the latest run's answers that name it, 0–100.

win_ratenumbernullable

Of the answers naming both, the share that name the brand first, 0–100. Null below min_co_appearances.

co_appearancesinteger

Answers that name both the brand and this competitor.

total_probesinteger

Answers in the latest run.

min_co_appearancesinteger

Shared answers needed before a head-to-head win rate is reported. Always 8.

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.