---
title: "Get Rankings"
method: GET
path: "/get-rankings"
tags: ["public-api"]
---

# Get Rankings

`GET /get-rankings`

## Request

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

Get competitive ranking data for your brand.

Views:
- overall (default): Visibility/ranking scores with per-competitor breakdown.
  Reads at most 90 days regardless of `days`; the response carries
  `days_requested`, `days_effective` and a `window_note` when they differ.
- by-prompt: Rankings per prompt across markets
- prompt-trends: Daily average position per prompt, for you and the
  competitors you meet on it. Answers which prompts you are losing, and
  since when. Position is average rank in the answer, so lower is better.

## Query parameters

- `brand_id` string, uuid, required: Brand UUID
- `view` string, nullable: View mode: overall (default), by-prompt
- `days` integer: Historical period in days, 1-365. view=overall reads at most 90 days and reports the window it actually used in days_effective.
- `include_volume` boolean: Merge search volume data into rankings
- `tag_ids` string, nullable: Comma-separated prompt tag UUIDs. Recalculates rankings over only the prompts carrying those tags. Applies to view=overall and view=prompt-trends.
- `limit` integer: view=prompt-trends only: how many prompts to return, most-measured 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
  - RankingsOverallResponse: GET /get-rankings (default)
    - `period` 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
    - `brand` object, required
    - `your_rank` integer, required
    - `total_competitors` integer, required
    - `your_visibility` number, required
    - `your_visibility_change` number, nullable
    - `win_rate` number, nullable
    - `threat_count` integer, nullable
    - `rankings` RankedBrand[], required
      - `rank` integer, required
      - `name` string, required
      - `visibility` number, required
      - `visibility_change` number, nullable
      - `is_you` boolean
      - `h2h_win_rate` number, nullable
    - `days_requested` integer, nullable
    - `days_effective` integer, nullable
    - `window_note` string, nullable
  - RankingsByPromptResponse: GET /get-rankings?view=by-prompt
    - `brand` object, required
    - `prompts` PromptRanking[], required
      - `prompt_id` string, required
      - `prompt_text` string, required
      - `markets` PromptMarketScore[], required
        - `market_id` string, nullable
        - `location` string, required
        - `location_region` string, nullable
        - `location_city` string, nullable
        - `is_primary` boolean, required
        - `score` number, required
        - `search_volume` integer, nullable
        - `priority_score` number, nullable
  - RankingsPromptTrendsResponse: GET /get-rankings?view=prompt-trends Position is average rank in the AI answer, so LOWER is better and a positive `position_change` means the brand slipped down the answer.
    - `brand` object, required
    - `prompts` PromptPositionSeries[], required
      - `prompt_text` string, required
      - `your_positions` PromptPositionSeriesPoint[]
        - `date` string, required
        - `position` number, required
      - `competitors` object
      - `days_with_data` integer
      - `best_position` number, nullable
      - `worst_position` number, nullable
      - `latest_position` number, nullable
      - `position_change` number, nullable
    - `period_days` integer, required
    - `total_prompts_with_trends` integer, required
    - `tag_ids` string[]
    - `data_through` string, nullable
    - `note` string

## 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)