Visibility rankings

Visibility rankings per AI model and per prompt, with optional search volume data.

Code example

Request

curl -X GET 'https://api.trakkr.ai/get-rankings?brand_id=00000000-0000-4000-8000-81f286d10c3c&days=30&include_volume=false&limit=25' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Response · 200 OK

{
  "brand": { "id": "...", "name": "Notion" },
  "your_rank": 2,
  "total_competitors": 6,
  "your_visibility": 72.4,
  "your_visibility_change": 3.1,
  "win_rate": 61.5,
  "threat_count": 2,
  "rankings": [
    {
      "rank": 1,
      "name": "Competitor A",
      "visibility": 79.8,
      "visibility_change": 1.2,
      "is_you": false,
      "h2h_win_rate": 48.5
    },
    {
      "rank": 2,
      "name": "Notion",
      "visibility": 72.4,
      "visibility_change": 3.1,
      "is_you": true,
      "h2h_win_rate": null
    }
  ]
}

Synthetic example. Values are made up.

API key required

60 req/min

Endpoint

GET/get-rankings

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

Request parameters

brand_idstringqueryRequired

Brand UUID

Format: uuid

viewstring | nullqueryOptional

View mode: overall (default), by-prompt

daysintegerqueryOptional

Historical period in days, 1-365. view=overall reads at most 90 days and reports the window it actually used in days_effective.

Default: 30 · Minimum: 1 · Maximum: 365

include_volumebooleanqueryOptional

Merge search volume data into rankings

Default: false

tag_idsstring | nullqueryOptional

Comma-separated prompt tag UUIDs. Recalculates rankings over only the prompts carrying those tags. Applies to view=overall and view=prompt-trends.

limitintegerqueryOptional

view=prompt-trends only: how many prompts to return, most-measured first.

Default: 25 · Minimum: 1 · Maximum: 100

periodstring | nullqueryOptional

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.

Responses and errors

200Successful Response

application/json

RankingsOverallResponse

periodobject | nullOptional

Fields in period

PeriodMeta

keystringRequired

kindstringRequired

labelstringRequired

startstringRequired

endstringRequired

statusstringRequired

sourcestringRequired

frozen_atstring | nullOptional

pipeline_versionstring | nullOptional

restated_atstring | nullOptional

restatementsobject[]Optional

Default: []

Fields in restatements

Array of object. Default: []

object. Additional keys are allowed.

coverageobjectOptional

Default: {}

fields_computedstring[]Optional

Default: []

Fields in fields_computed

Array of string. Default: []

string.

fields_missingstring[]Optional

Default: []

Fields in fields_missing

Array of string. Default: []

string.

notesstring[]Optional

Default: []

Fields in notes

Array of string. Default: []

string.

monthsobject | nullOptional

rank_sourcestring | nullOptional

null

null.

brandobjectRequired

your_rankintegerRequired

total_competitorsintegerRequired

your_visibilitynumberRequired

your_visibility_changenumber | nullOptional

your_visibility_avgnumber | nullOptional

your_visibility_avg_changenumber | nullOptional

your_rank_by_avginteger | nullOptional

rankings_by_avgobject[] | nullOptional

win_ratenumber | nullOptional

threat_countinteger | nullOptional

rankingsobject[]Required

Fields in rankings

Array of object.

rankintegerRequired

namestringRequired

visibilitynumberRequired

visibility_changenumber | nullOptional

is_youbooleanOptional

Default: false

h2h_win_ratenumber | nullOptional

days_requestedinteger | nullOptional

days_effectiveinteger | nullOptional

window_notestring | nullOptional

RankingsByPromptResponse

brandobjectRequired

promptsobject[]Required

Fields in prompts

Array of object.

prompt_idstringRequired

prompt_textstringRequired

marketsobject[]Required

Fields in markets

Array of object.

market_idstring | nullOptional

locationstringRequired

location_regionstring | nullOptional

location_citystring | nullOptional

is_primarybooleanRequired

scorenumberRequired

search_volumeinteger | nullOptional

priority_scorenumber | nullOptional

RankingsPromptTrendsResponse

brandobjectRequired

promptsobject[]Required

Fields in prompts

Array of object.

prompt_textstringRequired

your_positionsobject[]Optional

Default: []

Fields in your_positions

Array of object. Default: []

datestringRequired

positionnumberRequired

competitorsobjectOptional

Default: {}

days_with_dataintegerOptional

Default: 0

best_positionnumber | nullOptional

worst_positionnumber | nullOptional

latest_positionnumber | nullOptional

position_changenumber | nullOptional

period_daysintegerRequired

total_prompts_with_trendsintegerRequired

tag_idsstring[]Optional

Default: []

Fields in tag_ids

Array of string. Default: []

string.

data_throughstring | nullOptional

notestringOptional

Default: "position is average rank in the answer: lower is better, and a positive position_change means the brand slipped."

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source

Returns visibility ranking data for your brand across AI models. Use different view modes to get overall scores or per-prompt breakdowns with optional search volume enrichment.

This endpoint is rate limited to 60 requests per minute per API key. See the Rate Limits page for handling 429 responses.

Frozen periods. Pass period=2026-08 (a month) or period=2026-Q3 (a quarter) to read this endpoint from the monthly archive instead of a rolling window. A closed month answers identically however later it is asked; the open month is computed to date and says status: open. When period is set, days is ignored and the response carries a period block. Only view=overall reads a period (400 otherwise); win_rate and threat_count come back null, and a month with no archived rank returns 404. your_rank orders brands by visibility on the last measured day; your_rank_by_avg and rankings_by_avg order the same brands by their average daily visibility over the month (null on months archived before October 2026). See Periods.

Try GET /get-rankings

view=overall (default)

Returns aggregated visibility scores and ranking metrics across all AI models. This is the default view when no view parameter is provided.

Request

curl -X GET 'https://api.trakkr.ai/get-rankings?brand_id=00000000-0000-4000-8000-81f286d10c3c&days=30&include_volume=false&limit=25' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Response · 200 OK

{
  "brand": { "id": "...", "name": "Notion" },
  "your_rank": 2,
  "total_competitors": 6,
  "your_visibility": 72.4,
  "your_visibility_change": 3.1,
  "win_rate": 61.5,
  "threat_count": 2,
  "rankings": [
    {
      "rank": 1,
      "name": "Competitor A",
      "visibility": 79.8,
      "visibility_change": 1.2,
      "is_you": false,
      "h2h_win_rate": 48.5
    },
    {
      "rank": 2,
      "name": "Notion",
      "visibility": 72.4,
      "visibility_change": 3.1,
      "is_you": true,
      "h2h_win_rate": null
    }
  ]
}

Synthetic example. Values are made up.

view=by-prompt

Returns per-prompt ranking data with market-level breakdowns. Each prompt includes one or more markets entries with a location-specific visibility score.

Request

curl -X GET 'https://api.trakkr.ai/get-rankings?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=by-prompt&days=30&include_volume=false&limit=25' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Response · 200 OK

{
  "brand": { "id": "...", "name": "Notion" },
  "prompts": [
    {
      "prompt_id": "abc-123",
      "prompt_text": "best project management tools 2026",
      "markets": [
        {
          "location": "US",
          "is_primary": true,
          "score": 74.2
        },
        {
          "location": "UK",
          "is_primary": false,
          "score": 68.1
        }
      ]
    }
  ]
}

Synthetic example. Values are made up.

view=prompt-trends

Returns a daily position series per prompt for your brand and for the competitors you meet on that prompt. This is the view that answers which specific prompts you are losing, and since when, rather than only where you stand today.

Position is the average rank your brand holds in the answer, so lower is better. A positive position_change means the brand slipped down.

Request

curl -X GET 'https://api.trakkr.ai/get-rankings?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=prompt-trends&days=90&include_volume=false&limit=25' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Response · 200 OK

{
  "brand": { "id": "00000000-0000-4000-8000-81f286d10c3c", "name": "Notion" },
  "prompts": [
    {
      "prompt_text": "best project management tool",
      "your_positions": [
        { "date": "2026-08-18", "position": 2.0 },
        { "date": "2026-08-24", "position": 4.0 }
      ],
      "competitors": {
        "Coda": [
          { "date": "2026-08-18", "position": 3.0 },
          { "date": "2026-08-24", "position": 1.0 }
        ]
      },
      "days_with_data": 2,
      "best_position": 2.0,
      "worst_position": 4.0,
      "latest_position": 4.0,
      "position_change": 2.0
    }
  ],
  "period_days": 90,
  "total_prompts_with_trends": 34,
  "tag_ids": [],
  "data_through": "2026-08-24",
  "note": "position is average rank in the answer: lower is better, and a positive position_change means the brand slipped."
}

Synthetic example. Values are made up.

Prompts come back most-measured first. Use limit to control how many you receive and total_prompts_with_trends to see how many exist. A window shorter than 7 days is widened to 7, and anything above 90 is held at 90, which is the depth the pipeline keeps.

Filtering by tag

Pass tag_ids to recalculate view=overall or view=prompt-trends over only the prompts carrying those tags. Tag UUIDs come from /get-tags. The response echoes the tags it used so a filtered slice is never mistaken for the whole picture.

include_volume

Add include_volume=true to any view=by-prompt request to merge search demand signals into each market row. You will receivesearch_volume and priority_scoreinside each markets[] item when available.

Request with Volume

curl -X GET 'https://api.trakkr.ai/get-rankings?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=by-prompt&days=30&include_volume=true&limit=25' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Response · 200 OK

{
  "brand": { "id": "...", "name": "Notion" },
  "prompts": [
    {
      "prompt_id": "abc-123",
      "prompt_text": "best project management tools 2026",
      "markets": [
        {
          "location": "US",
          "is_primary": true,
          "score": 74.2,
          "search_volume": 12400,
          "priority_score": 82.0
        }
      ]
    }
  ]
}

Synthetic example. Values are made up.

Use volume data to prioritize prompts where you rank well AND have high search traffic. Sort by markets[].search_volume descending to find your highest-impact opportunities.

Use Cases

Track overall brand visibility across all AI models
Identify which models favor your brand and which need improvement
Analyze per-prompt performance to find optimization opportunities
Prioritize high-volume prompts with include_volume=true
Monitor ranking trends over different time periods with the days parameter
Find the prompts you are losing, and when it started, with view=prompt-trends
Report on a single business line by passing tag_ids

Request

curl -X GET 'https://api.trakkr.ai/get-rankings?brand_id=00000000-0000-4000-8000-81f286d10c3c&days=30&include_volume=false&limit=25' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Response · 200 OK

{
  "brand": { "id": "...", "name": "Notion" },
  "your_rank": 2,
  "total_competitors": 6,
  "your_visibility": 72.4,
  "your_visibility_change": 3.1,
  "win_rate": 61.5,
  "threat_count": 2,
  "rankings": [
    {
      "rank": 1,
      "name": "Competitor A",
      "visibility": 79.8,
      "visibility_change": 1.2,
      "is_you": false,
      "h2h_win_rate": 48.5
    },
    {
      "rank": 2,
      "name": "Notion",
      "visibility": 72.4,
      "visibility_change": 3.1,
      "is_you": true,
      "h2h_win_rate": null
    }
  ]
}

Synthetic example. Values are made up.