---
title: "Get Competitor Data"
method: GET
path: "/get-competitor-data"
tags: ["public-api"]
---

# Get Competitor Data

`GET /get-competitor-data`

## Request

- Base URL: `https://api.trakkr.ai`
- URL: `https://api.trakkr.ai/get-competitor-data`
- Auth: HTTP bearer

Get competitor analysis data. Use the `view` parameter to select different data views.

Every view honours `days` and `tag_ids`, so a view can be scoped to one
business line and one window in a single call.

Views:
- summary (default): Performance summary and head-to-head comparisons
- arena: All prompts ranked as battlegrounds
- head-to-head: Direct 1v1 comparison (requires `competitor` param)
- by-model: Competitor breakdown per AI model
- threats: Emerging competitor threats and opportunities
- heatmap: Competitor presence matrix across models
- over_time: Daily visibility per brand, you and your competitors

## Query parameters

- `brand_id` string, uuid, nullable: Brand UUID
- `brand` string, uuid, nullable: Alias for brand_id
- `view` string, nullable: View mode: summary (default), arena, head-to-head, by-model, threats, heatmap, over_time
- `competitor` string, nullable: Competitor name. Required when view=head-to-head; on view=over_time it returns just you and that competitor.
- `days` integer: History window every view is computed over. One of 7, 14, 30, 90.
- `tag_ids` string, nullable: Comma-separated prompt tag UUIDs. Every metric in the response is recalculated over only the prompts carrying those tags, exactly as the Competitors page does when you filter by tag.
- `limit` integer: view=over_time only: how many competitor series to return, ranked best first.
- `period` string, nullable: A frozen calendar period instead of a rolling window: a month as YYYY-MM (2026-08) or a quarter as YYYY-Qn (2026-Q3). A closed month is read from the archive frozen when it closed; the open month is computed to date. When period is given, days is ignored and the response carries a `period` block saying exactly what was resolved. Definitions: /get-metrics.

## Response `200`

Successful Response

- union
  - CompetitorPeriodResponse: GET /get-competitor-data?period=YYYY-MM (view=summary)
    - `brand` object, required
    - `period` PeriodMeta, required: What a period-scoped response actually resolved.
      - `key` string, required
      - `kind` string, required
      - `label` string, required
      - `start` string, required
      - `end` string, required
      - `status` string, required
      - `source` string, required
      - `frozen_at` string, nullable
      - `pipeline_version` string, nullable
      - `restated_at` string, nullable
      - `restatements` object[]
      - `coverage` object
      - `fields_computed` string[]
      - `fields_missing` string[]
      - `notes` string[]
      - `months` object, nullable
      - `rank_source` string, nullable
    - `prior` PeriodMeta: What a period-scoped response actually resolved.
      - `key` string, required
      - `kind` string, required
      - `label` string, required
      - `start` string, required
      - `end` string, required
      - `status` string, required
      - `source` string, required
      - `frozen_at` string, nullable
      - `pipeline_version` string, nullable
      - `restated_at` string, nullable
      - `restatements` object[]
      - `coverage` object
      - `fields_computed` string[]
      - `fields_missing` string[]
      - `notes` string[]
      - `months` object, nullable
      - `rank_source` string, nullable
    - `your_rank` integer, nullable
    - `rank_pool` integer, nullable
    - `your_visibility` number, nullable
    - `competitors` CompetitorPeriodEntry[]
      - `name` string, required
      - `rank` integer, nullable
      - `visibility` number, nullable
      - `is_you` boolean
      - `prior_rank` integer, nullable
      - `prior_visibility` number, nullable
      - `positions_gained` integer, nullable
      - `visibility_delta` number, nullable
      - `new_in_list` boolean, nullable
    - `notable_change` object, nullable
    - `perception_competitors` object[]
  - CompetitorDataResponse: GET /get-competitor-data response.
    - `brand_performance_summary` BrandPerformance[], required
      - `brand_name` string, required
      - `total_mentions` integer, required
      - `avg_rank` number, required
    - `top_spot_ownership` TopSpotOwnership[], required
      - `prompt` string, required
      - `top_brand` string, required
      - `count` integer, required
    - `primary_brand_cooccurrences` CoOccurrence[], required
      - `competitor` string, required
      - `count` integer, required
      - `primary_wins_pct` number, required
    - `filters_applied` CompetitorFiltersApplied: The scope a competitor response was actually computed over. Competitor views honour `days` and `tag_ids`, and an agency slicing a client by business line needs the answer to say which slice it is. Echoing the scope also stops an assistant presenting a tag-filtered number as the brand's overall position.
      - `days` integer, required
      - `tag_ids` string[]
      - `prompts_in_scope` integer, nullable
  - CompetitorArenaResponse: GET /get-competitor-data?view=arena
    - `prompts` CompetitorArenaPrompt[], required
      - `prompt_text` string, required
      - `your_rank` integer, required
      - `your_score` number, nullable
      - `leader` string, required
      - `leader_score` number, nullable
      - `gap_to_leader` number, required
      - `total_competitors` integer, required
      - `rankings` CompetitorArenaRanking[], required
        - `rank` integer, required
        - `name` string, required
        - `score` number, required
        - `is_you` boolean
    - `total_prompts` integer, required
    - `prompts_you_lead` integer, required
    - `prompts_top_3` integer, required
  - CompetitorH2HResponse: GET /get-competitor-data?view=head-to-head
    - `you` CompetitorBrandStats, required
      - `name` string, required
      - `visibility` number, required
      - `visibility_change` number, nullable
      - `avg_rank` number, nullable
      - `rank1_count` integer
    - `rival` CompetitorBrandStats, required
      - `name` string, required
      - `visibility` number, required
      - `visibility_change` number, nullable
      - `avg_rank` number, nullable
      - `rank1_count` integer
    - `head_to_head` CompetitorH2HRecord, required
      - `your_wins` integer, required
      - `rival_wins` integer, required
      - `ties` integer, required
      - `your_win_rate` number, required
      - `total_matchups` integer, required
    - `where_rival_wins` CompetitorPromptMatchup[], required
      - `prompt_text` string, required
      - `your_rank` integer, required
      - `rival_rank` integer, required
    - `where_you_win` CompetitorPromptMatchup[], required
      - `prompt_text` string, required
      - `your_rank` integer, required
      - `rival_rank` integer, required
    - `available_rivals` string[], required
    - `filters_applied` CompetitorFiltersApplied: The scope a competitor response was actually computed over. Competitor views honour `days` and `tag_ids`, and an agency slicing a client by business line needs the answer to say which slice it is. Echoing the scope also stops an assistant presenting a tag-filtered number as the brand's overall position.
      - `days` integer, required
      - `tag_ids` string[]
      - `prompts_in_scope` integer, nullable
  - CompetitorByModelResponse: GET /get-competitor-data?view=by-model
    - `llms` string[], required
    - `brands` string[], required
    - `your_brand` string, required
    - `heatmap` CompetitorLLMCell[], required
      - `brand` string, required
      - `llm` string, required
      - `visibility` number, required
      - `avg_rank` number, nullable
      - `mentions` integer, required
      - `is_you` boolean
    - `insights` CompetitorLLMInsight[], required
      - `type` string, required
      - `llm` string, nullable
      - `message` string, required
    - `your_best_llm` string, nullable
    - `your_worst_llm` string, nullable
  - CompetitorThreatsResponse: GET /get-competitor-data?view=threats
    - `threats` CompetitorThreatItem[], required
      - `competitor` string, required
      - `severity` string, required
      - `pressure_score` number, required
      - `win_rate_against_you` number, required
      - `cooccurrence_count` integer, required
      - `trend` string, required
      - `description` string, required
    - `opportunities` CompetitorOpportunityItem[], required
      - `prompt_text` string, required
      - `your_rank` integer, required
      - `gap_to_next` number, required
      - `next_competitor` string, required
      - `opportunity_score` number, required
      - `category` string, nullable
    - `alerts` CompetitorAlertItem[], required
      - `type` string, required
      - `severity` string, required
      - `message` string, required
      - `prompt` string, nullable
      - `competitor` string, nullable
    - `summary` object, required
  - CompetitorHeatmapResponse: GET /get-competitor-data?view=heatmap
    - `brands` string[], required
    - `models` string[], required
    - `your_brand` string, required
    - `cells` CompetitorHeatmapCell[], required
      - `brand` string, required
      - `model` string, required
      - `visibility` number, required
      - `avg_rank` number, nullable
      - `mentions` integer
      - `is_you` boolean
    - `your_best_model` string, nullable
    - `your_worst_model` string, nullable
  - CompetitorOverTimeResponse: GET /get-competitor-data?view=over_time
    - `brands` CompetitorOverTimeBrand[], required
      - `name` string, required
      - `is_you` boolean
      - `rank` integer, nullable
      - `visibility` number, nullable
      - `data_points` object[], required
    - `period_days` integer, required
    - `date_range` object, required
    - `your_brand` string, nullable
    - `data_through` string, nullable
    - `filters_applied` CompetitorFiltersApplied: The scope a competitor response was actually computed over. Competitor views honour `days` and `tag_ids`, and an agency slicing a client by business line needs the answer to say which slice it is. Echoing the scope also stops an assistant presenting a tag-filtered number as the brand's overall position.
      - `days` integer, required
      - `tag_ids` string[]
      - `prompts_in_scope` integer, nullable

## Other responses

- `401`: Missing, malformed, or expired credentials
- `402`: The current plan does not fund this operation
- `403`: Invalid credentials, missing brand access, or insufficient role
- `422`: Validation Error
- `429`: Rate limit exceeded
- `500`: The operation failed
- `503`: Authentication, entitlement, or a required dependency is temporarily unavailable

---

[API](https://skmtc.dev/trakkr/apis/trakkr-api.md) · [All operations](https://skmtc.dev/trakkr/apis/trakkr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trakkr/apis/trakkr-api/revisions/189a9e76b8d5?raw)