---
title: "Get Perception"
method: GET
path: "/get-perception"
tags: ["public-api"]
---

# Get Perception

`GET /get-perception`

## Request

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

Get perception data for a brand.

Views:
- dashboard (default): full perception dashboard — scores, time series,
  competitor gaps, radar chart data
- metrics: raw metric_history rows (optionally filter by tracked_brand)
- narrative: latest positioning summary — strengths, weaknesses, opportunities
- story: weekly story / narrative arc payload that drives the Story tab
- narrative_drift: how the brand's narrative has shifted over `weeks` weeks
  (used by the Goals tab)

Requires a paid plan.

## Query parameters

- `brand_id` string, uuid, required: Brand UUID
- `view` 'dashboard' | 'metrics' | 'narrative' | 'story' | 'narrative_drift': View type: dashboard, metrics, narrative, story, or narrative_drift
- `days` integer: Number of days of data (dashboard/metrics views)
- `weeks` integer: Number of weeks for narrative_drift view
- `tracked_brand` string, nullable: Filter by specific tracked brand (metrics view only)
- `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
  - PerceptionDashboardApiResponse: GET /get-perception?view=dashboard response.
    - `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
    - `metadata` PerceptionMetadataApi, required: Metadata for perception dashboard response.
      - `brand_id` string, required
      - `primary_brand` string, required
      - `date_range_start` string, nullable
      - `date_range_end` string, nullable
      - `total_brands_tracked` integer
      - `days_of_data` integer
    - `perception_score` PerceptionScoreApi, required: Perception score summary.
      - `score` number, nullable
      - `change_7d` number, nullable
      - `percentile` number, nullable
      - `change_period` number, nullable
    - `category_scores` object
    - `insights` object
    - `brand_summaries` PerceptionBrandSummaryApi[]
      - `brand_name` string, required
      - `is_primary` boolean
      - `rank_1_in` string[]
      - `rank_last_in` string[]
    - `detailed_sentiment_timeseries` PerceptionBrandTimeSeriesApi[]
      - `brand_name` string, required
      - `is_primary` boolean
      - `metrics` PerceptionMetricTimeSeriesApi[]
        - `metric_name` string, required
        - `series` PerceptionMetricSeriesPointApi[]
          - `date` string, required
          - `score` number, nullable
        - `average_7_day` number, nullable
    - `competitor_gaps` PerceptionCompetitorGapApi[]
      - `competitor` string, required
      - `your_advantages` string[]
      - `their_advantages` string[]
      - `biggest_gap_for_you` string, nullable
      - `biggest_gap_against_you` string, nullable
    - `radar_chart_data` PerceptionRadarBrandApi[]
      - `name` string, required
      - `is_primary` boolean
      - `data` PerceptionRadarPointApi[]
        - `axis` string, required
        - `value` number, required
    - `metric_rankings` object
    - `primary_brand_overall_timeseries` PerceptionMetricSeriesPointApi[]
      - `date` string, required
      - `score` number, nullable
  - PerceptionMetricsApiResponse: GET /get-perception?view=metrics response.
    - `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_id` string, required
    - `tracked_brand` string, nullable
    - `days` integer, required
    - `count` integer, required
    - `data` object[]
  - PerceptionNarrativeApiResponse: GET /get-perception?view=narrative response.
    - `brand_id` string, required
    - `narrative` PerceptionNarrativeData: Perception narrative analysis data.
      - `positioning` string, nullable
      - `strengths` string[]
      - `weaknesses` string[]
      - `opportunities` string[]
      - `sentiment_summary` string, nullable
    - `snapshot_date` string, nullable
  - PerceptionStoryApiResponse: GET /get-perception?view=story response.
    - `brand_id` string, required
    - `story` PerceptionStoryDataApi, required: Stable story envelope; analysis collections retain their open entry shapes.
      - `run_date` string, nullable, required
      - `brand_id` string, required
      - `total_prompts_analyzed` integer, required
      - `total_responses_processed` integer, required
      - `narrative` PerceptionStoryNarrativeApi, required
        - `summary` string, required: May be empty when no written summary is available.
        - `positioning` string, required
        - `tone` '', required: Retained for compatibility; always empty.
        - `key_themes` unknown[], required: Analysis entries; individual entry shapes may vary.
          - unknown
      - `perception_score` number, nullable, required
      - `perception_percentile` number, nullable, required
      - `perception_change_7d` number, nullable, required
      - `semantic_dna` PerceptionStorySemanticDnaApi, required
        - `semantic_dna` unknown[], required
          - unknown
        - `primary_descriptors` unknown[], required
          - unknown
        - `emerging_descriptors` unknown[], required
          - unknown
        - `fading_descriptors` unknown[], required
          - unknown
      - `use_case_mapping` PerceptionStoryUseCasesApi, required
        - `winning_use_cases` unknown[], required
          - unknown
        - `losing_use_cases` unknown[], required
          - unknown
        - `use_case_coverage_score` number, required
      - `perception_gaps` PerceptionStoryGapsApi, required
        - `perception_gaps` unknown[], required
          - unknown
        - `alignment_score` number, required
      - `common_concerns` unknown[], required
        - unknown
      - `category_scores` object, required
      - `model_breakdown` object, required
      - `recommendations` unknown[], required
        - unknown
      - `top_cited_domains` unknown[], required
        - unknown
      - `source_perception_map` unknown[], required
        - unknown
      - `competitor_narratives` object, required
  - object
  - PerceptionDashboardApiResponse: GET /get-perception?view=dashboard response.
    - `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
    - `metadata` PerceptionMetadataApi, required: Metadata for perception dashboard response.
      - `brand_id` string, required
      - `primary_brand` string, required
      - `date_range_start` string, nullable
      - `date_range_end` string, nullable
      - `total_brands_tracked` integer
      - `days_of_data` integer
    - `perception_score` PerceptionScoreApi, required: Perception score summary.
      - `score` number, nullable
      - `change_7d` number, nullable
      - `percentile` number, nullable
      - `change_period` number, nullable
    - `category_scores` object
    - `insights` object
    - `brand_summaries` PerceptionBrandSummaryApi[]
      - `brand_name` string, required
      - `is_primary` boolean
      - `rank_1_in` string[]
      - `rank_last_in` string[]
    - `detailed_sentiment_timeseries` PerceptionBrandTimeSeriesApi[]
      - `brand_name` string, required
      - `is_primary` boolean
      - `metrics` PerceptionMetricTimeSeriesApi[]
        - `metric_name` string, required
        - `series` PerceptionMetricSeriesPointApi[]
          - `date` string, required
          - `score` number, nullable
        - `average_7_day` number, nullable
    - `competitor_gaps` PerceptionCompetitorGapApi[]
      - `competitor` string, required
      - `your_advantages` string[]
      - `their_advantages` string[]
      - `biggest_gap_for_you` string, nullable
      - `biggest_gap_against_you` string, nullable
    - `radar_chart_data` PerceptionRadarBrandApi[]
      - `name` string, required
      - `is_primary` boolean
      - `data` PerceptionRadarPointApi[]
        - `axis` string, required
        - `value` number, required
    - `metric_rankings` object
    - `primary_brand_overall_timeseries` PerceptionMetricSeriesPointApi[]
      - `date` string, required
      - `score` number, nullable
  - PerceptionMetricsApiResponse: GET /get-perception?view=metrics response.
    - `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_id` string, required
    - `tracked_brand` string, nullable
    - `days` integer, required
    - `count` integer, required
    - `data` object[]
  - PerceptionNarrativeApiResponse: GET /get-perception?view=narrative response.
    - `brand_id` string, required
    - `narrative` PerceptionNarrativeData: Perception narrative analysis data.
      - `positioning` string, nullable
      - `strengths` string[]
      - `weaknesses` string[]
      - `opportunities` string[]
      - `sentiment_summary` string, nullable
    - `snapshot_date` string, nullable
  - PerceptionStoryApiResponse: GET /get-perception?view=story response.
    - `brand_id` string, required
    - `story` PerceptionStoryDataApi, required: Stable story envelope; analysis collections retain their open entry shapes.
      - `run_date` string, nullable, required
      - `brand_id` string, required
      - `total_prompts_analyzed` integer, required
      - `total_responses_processed` integer, required
      - `narrative` PerceptionStoryNarrativeApi, required
        - `summary` string, required: May be empty when no written summary is available.
        - `positioning` string, required
        - `tone` '', required: Retained for compatibility; always empty.
        - `key_themes` unknown[], required: Analysis entries; individual entry shapes may vary.
          - unknown
      - `perception_score` number, nullable, required
      - `perception_percentile` number, nullable, required
      - `perception_change_7d` number, nullable, required
      - `semantic_dna` PerceptionStorySemanticDnaApi, required
        - `semantic_dna` unknown[], required
          - unknown
        - `primary_descriptors` unknown[], required
          - unknown
        - `emerging_descriptors` unknown[], required
          - unknown
        - `fading_descriptors` unknown[], required
          - unknown
      - `use_case_mapping` PerceptionStoryUseCasesApi, required
        - `winning_use_cases` unknown[], required
          - unknown
        - `losing_use_cases` unknown[], required
          - unknown
        - `use_case_coverage_score` number, required
      - `perception_gaps` PerceptionStoryGapsApi, required
        - `perception_gaps` unknown[], required
          - unknown
        - `alignment_score` number, required
      - `common_concerns` unknown[], required
        - unknown
      - `category_scores` object, required
      - `model_breakdown` object, required
      - `recommendations` unknown[], required
        - unknown
      - `top_cited_domains` unknown[], required
        - unknown
      - `source_perception_map` unknown[], required
        - unknown
      - `competitor_narratives` object, required
  - PerceptionNarrativeDriftApiResponse: GET /get-perception?view=narrative_drift response.
    - `brand_id` string, required
    - `weeks` integer, required
    - `drift` PerceptionNarrativeDriftDataApi, required
      - `history` PerceptionNarrativeDriftPointApi[], required
        - `id` string, nullable, required
        - `run_date` string, nullable, required
        - `positioning_statement` string, required
        - `brand_tone` string, required
        - `primary_descriptors` unknown[], required
          - unknown
        - `perception_score` number, required
        - `positioning_changed` boolean, required
        - `tone_changed` boolean, required
        - `new_descriptors` unknown[], required
          - unknown
        - `lost_descriptors` unknown[], required
          - unknown
        - `diff` object, nullable, required
      - `total_weeks` integer, required
      - `significant_changes` integer, required
  - object

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