Skip to content
TrakkrLearnAPI
Sign in

Perception

Access AI perception data - understand how AI models perceive your brand across trust, quality, value, market position, and innovation.

Code example

Dashboard View
curl -X GET 'https://api.trakkr.ai/get-perception?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=dashboard&days=90&weeks=8' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
Response · 200 OK
{
  "metadata": {
    "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
    "primary_brand": "Notion",
    "date_range_start": "2025-12-01",
    "date_range_end": "2026-03-01",
    "total_brands_tracked": 4,
    "days_of_data": 90
  },
  "perception_score": {
    "score": 72.5,
    "change_7d": 1.3,
    "percentile": 82.0
  },
  "category_scores": {
    "trust_reliability": 78.2,
    "quality_performance": 71.0,
    "value_experience": 68.5,
    "market_position": 75.3,
    "innovation_appeal": 69.8
  },
  "insights": {
    "strengths": ["High trust scores across all models", "Strong brand recognition"],
    "opportunities": ["Improve value perception", "Increase adaptability messaging"]
  },
  "brand_summaries": [
    {
      "brand_name": "Notion",
      "is_primary": true,
      "rank_1_in": ["overall_quality", "ease_of_interaction"],
      "rank_last_in": []
    }
  ],
  "competitor_gaps": [
    {
      "competitor": "Coda",
      "your_advantages": ["overall_trust", "brand_recognition"],
      "their_advantages": ["value_for_money"],
      "biggest_gap_for_you": "value_for_money",
      "biggest_gap_against_you": null
    }
  ],
  "primary_brand_overall_timeseries": [
    {"date": "2026-02-01", "score": 71.2},
    {"date": "2026-02-08", "score": 72.5}
  ]
}

Synthetic example. Values are made up.

API key required

60 req/min

Overview

The Perception API provides access to how AI models such as ChatGPT, Claude, Gemini and Perplexity perceive your brand across 20 metrics grouped into 5 categories: Trust & Reliability, Quality & Performance, Value & Experience, Market Position, and Innovation & Appeal.

The dashboard view returns the same rich data powering the Perception page in the Trakkr app.

Get Dashboard

GET/get-perceptionReturns full perception dashboard: scores, time series, competitor gaps, and radar data.

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

Request parameters

brand_idstringqueryRequired

Brand UUID

Format: uuid

viewstringqueryOptional

View type: dashboard, metrics, narrative, story, or narrative_drift

Default: "dashboard" · Options: "dashboard", "metrics", "narrative", "story", "narrative_drift"

daysintegerqueryOptional

Number of days of data (dashboard/metrics views)

Default: 90 · Minimum: 7 · Maximum: 365

weeksintegerqueryOptional

Number of weeks for narrative_drift view

Default: 8 · Minimum: 1 · Maximum: 52

tracked_brandstring | nullqueryOptional

Filter by specific tracked brand (metrics view only)

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

PerceptionDashboardApiResponse

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.

metadataobjectRequired

Metadata for perception dashboard response.

Fields in metadata

brand_idstringRequired

primary_brandstringRequired

date_range_startstring | nullOptional

date_range_endstring | nullOptional

total_brands_trackedintegerOptional

Default: 0

days_of_dataintegerOptional

Default: 0

perception_scoreobjectRequired

Perception score summary.

Fields in perception_score

scorenumber | nullOptional

change_7dnumber | nullOptional

percentilenumber | nullOptional

change_periodnumber | nullOptional

category_scoresobjectOptional

Default: {}

insightsobjectOptional

Default: {}

brand_summariesobject[]Optional

Default: []

Fields in brand_summaries

Array of object. Default: []

brand_namestringRequired

is_primarybooleanOptional

Default: false

rank_1_instring[]Optional

Default: []

Fields in rank_1_in

Array of string. Default: []

string.

rank_last_instring[]Optional

Default: []

Fields in rank_last_in

Array of string. Default: []

string.

detailed_sentiment_timeseriesobject[]Optional

Default: []

Fields in detailed_sentiment_timeseries

Array of object. Default: []

brand_namestringRequired

is_primarybooleanOptional

Default: false

metricsobject[]Optional

Default: []

Fields in metrics

Array of object. Default: []

metric_namestringRequired

seriesobject[]Optional

Default: []

Fields in series

Array of object. Default: []

datestringRequired

scorenumber | nullOptional

average_7_daynumber | nullOptional

competitor_gapsobject[]Optional

Default: []

Fields in competitor_gaps

Array of object. Default: []

competitorstringRequired

your_advantagesstring[]Optional

Default: []

Fields in your_advantages

Array of string. Default: []

string.

their_advantagesstring[]Optional

Default: []

Fields in their_advantages

Array of string. Default: []

string.

biggest_gap_for_youstring | nullOptional

biggest_gap_against_youstring | nullOptional

radar_chart_dataobject[]Optional

Default: []

Fields in radar_chart_data

Array of object. Default: []

namestringRequired

is_primarybooleanOptional

Default: false

dataobject[]Optional

Default: []

Fields in data

Array of object. Default: []

axisstringRequired

valuenumberRequired

metric_rankingsobjectOptional

Default: {}

primary_brand_overall_timeseriesobject[]Optional

Default: []

Fields in primary_brand_overall_timeseries

Array of object. Default: []

datestringRequired

scorenumber | nullOptional

PerceptionMetricsApiResponse

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.

brand_idstringRequired

tracked_brandstring | nullOptional

daysintegerRequired

countintegerRequired

dataobject[]Optional

Default: []

Fields in data

Array of object. Default: []

object. Additional keys are allowed.

PerceptionNarrativeApiResponse

brand_idstringRequired

narrativeobject | nullOptional

Fields in narrative
PerceptionNarrativeData

positioningstring | nullOptional

strengthsstring[]Optional

Default: []

Fields in strengths

Array of string. Default: []

string.

weaknessesstring[]Optional

Default: []

Fields in weaknesses

Array of string. Default: []

string.

opportunitiesstring[]Optional

Default: []

Fields in opportunities

Array of string. Default: []

string.

sentiment_summarystring | nullOptional

null

null.

snapshot_datestring | nullOptional

PerceptionStoryApiResponse

brand_idstringRequired

storyobject | nullRequired

Latest weekly story, or null when no story is available. Collection entries and keyed analysis values are open JSON shapes.

Fields in story
PerceptionStoryDataApi

run_datestring | nullRequired

brand_idstringRequired

total_prompts_analyzedintegerRequired

total_responses_processedintegerRequired

narrativeobjectRequired

Fields in narrative

summarystringRequired

May be empty when no written summary is available.

positioningstringRequired

tonestringRequired

Retained for compatibility; always empty.

key_themesany JSON value[]Required

Analysis entries; individual entry shapes may vary.

Fields in key_themes

Array of any JSON value.

any JSON value.

perception_scorenumber | nullRequired

perception_percentilenumber | nullRequired

perception_change_7dnumber | nullRequired

semantic_dnaobjectRequired

Fields in semantic_dna

semantic_dnaany JSON value[]Required

Fields in semantic_dna

Array of any JSON value.

any JSON value.

primary_descriptorsany JSON value[]Required

Fields in primary_descriptors

Array of any JSON value.

any JSON value.

emerging_descriptorsany JSON value[]Required

Fields in emerging_descriptors

Array of any JSON value.

any JSON value.

fading_descriptorsany JSON value[]Required

Fields in fading_descriptors

Array of any JSON value.

any JSON value.

use_case_mappingobjectRequired

Fields in use_case_mapping

winning_use_casesany JSON value[]Required

Fields in winning_use_cases

Array of any JSON value.

any JSON value.

losing_use_casesany JSON value[]Required

Fields in losing_use_cases

Array of any JSON value.

any JSON value.

use_case_coverage_scorenumberRequired

perception_gapsobjectRequired

Fields in perception_gaps

perception_gapsany JSON value[]Required

Fields in perception_gaps

Array of any JSON value.

any JSON value.

alignment_scorenumberRequired

common_concernsany JSON value[]Required

Fields in common_concerns

Array of any JSON value.

any JSON value.

category_scoresobjectRequired

model_breakdownobjectRequired

recommendationsany JSON value[]Required

Fields in recommendations

Array of any JSON value.

any JSON value.

top_cited_domainsany JSON value[]Required

Fields in top_cited_domains

Array of any JSON value.

any JSON value.

source_perception_mapany JSON value[]Required

Fields in source_perception_map

Array of any JSON value.

any JSON value.

competitor_narrativesobjectRequired

null

null.

object

object. Additional keys are allowed.

PerceptionDashboardApiResponse

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.

metadataobjectRequired

Metadata for perception dashboard response.

Fields in metadata

brand_idstringRequired

primary_brandstringRequired

date_range_startstring | nullOptional

date_range_endstring | nullOptional

total_brands_trackedintegerOptional

Default: 0

days_of_dataintegerOptional

Default: 0

perception_scoreobjectRequired

Perception score summary.

Fields in perception_score

scorenumber | nullOptional

change_7dnumber | nullOptional

percentilenumber | nullOptional

change_periodnumber | nullOptional

category_scoresobjectOptional

Default: {}

insightsobjectOptional

Default: {}

brand_summariesobject[]Optional

Default: []

Fields in brand_summaries

Array of object. Default: []

brand_namestringRequired

is_primarybooleanOptional

Default: false

rank_1_instring[]Optional

Default: []

Fields in rank_1_in

Array of string. Default: []

string.

rank_last_instring[]Optional

Default: []

Fields in rank_last_in

Array of string. Default: []

string.

detailed_sentiment_timeseriesobject[]Optional

Default: []

Fields in detailed_sentiment_timeseries

Array of object. Default: []

brand_namestringRequired

is_primarybooleanOptional

Default: false

metricsobject[]Optional

Default: []

Fields in metrics

Array of object. Default: []

metric_namestringRequired

seriesobject[]Optional

Default: []

Fields in series

Array of object. Default: []

datestringRequired

scorenumber | nullOptional

average_7_daynumber | nullOptional

competitor_gapsobject[]Optional

Default: []

Fields in competitor_gaps

Array of object. Default: []

competitorstringRequired

your_advantagesstring[]Optional

Default: []

Fields in your_advantages

Array of string. Default: []

string.

their_advantagesstring[]Optional

Default: []

Fields in their_advantages

Array of string. Default: []

string.

biggest_gap_for_youstring | nullOptional

biggest_gap_against_youstring | nullOptional

radar_chart_dataobject[]Optional

Default: []

Fields in radar_chart_data

Array of object. Default: []

namestringRequired

is_primarybooleanOptional

Default: false

dataobject[]Optional

Default: []

Fields in data

Array of object. Default: []

axisstringRequired

valuenumberRequired

metric_rankingsobjectOptional

Default: {}

primary_brand_overall_timeseriesobject[]Optional

Default: []

Fields in primary_brand_overall_timeseries

Array of object. Default: []

datestringRequired

scorenumber | nullOptional

PerceptionMetricsApiResponse

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.

brand_idstringRequired

tracked_brandstring | nullOptional

daysintegerRequired

countintegerRequired

dataobject[]Optional

Default: []

Fields in data

Array of object. Default: []

object. Additional keys are allowed.

PerceptionNarrativeApiResponse

brand_idstringRequired

narrativeobject | nullOptional

Fields in narrative
PerceptionNarrativeData

positioningstring | nullOptional

strengthsstring[]Optional

Default: []

Fields in strengths

Array of string. Default: []

string.

weaknessesstring[]Optional

Default: []

Fields in weaknesses

Array of string. Default: []

string.

opportunitiesstring[]Optional

Default: []

Fields in opportunities

Array of string. Default: []

string.

sentiment_summarystring | nullOptional

null

null.

snapshot_datestring | nullOptional

PerceptionStoryApiResponse

brand_idstringRequired

storyobject | nullRequired

Latest weekly story, or null when no story is available. Collection entries and keyed analysis values are open JSON shapes.

Fields in story
PerceptionStoryDataApi

run_datestring | nullRequired

brand_idstringRequired

total_prompts_analyzedintegerRequired

total_responses_processedintegerRequired

narrativeobjectRequired

Fields in narrative

summarystringRequired

May be empty when no written summary is available.

positioningstringRequired

tonestringRequired

Retained for compatibility; always empty.

key_themesany JSON value[]Required

Analysis entries; individual entry shapes may vary.

Fields in key_themes

Array of any JSON value.

any JSON value.

perception_scorenumber | nullRequired

perception_percentilenumber | nullRequired

perception_change_7dnumber | nullRequired

semantic_dnaobjectRequired

Fields in semantic_dna

semantic_dnaany JSON value[]Required

Fields in semantic_dna

Array of any JSON value.

any JSON value.

primary_descriptorsany JSON value[]Required

Fields in primary_descriptors

Array of any JSON value.

any JSON value.

emerging_descriptorsany JSON value[]Required

Fields in emerging_descriptors

Array of any JSON value.

any JSON value.

fading_descriptorsany JSON value[]Required

Fields in fading_descriptors

Array of any JSON value.

any JSON value.

use_case_mappingobjectRequired

Fields in use_case_mapping

winning_use_casesany JSON value[]Required

Fields in winning_use_cases

Array of any JSON value.

any JSON value.

losing_use_casesany JSON value[]Required

Fields in losing_use_cases

Array of any JSON value.

any JSON value.

use_case_coverage_scorenumberRequired

perception_gapsobjectRequired

Fields in perception_gaps

perception_gapsany JSON value[]Required

Fields in perception_gaps

Array of any JSON value.

any JSON value.

alignment_scorenumberRequired

common_concernsany JSON value[]Required

Fields in common_concerns

Array of any JSON value.

any JSON value.

category_scoresobjectRequired

model_breakdownobjectRequired

recommendationsany JSON value[]Required

Fields in recommendations

Array of any JSON value.

any JSON value.

top_cited_domainsany JSON value[]Required

Fields in top_cited_domains

Array of any JSON value.

any JSON value.

source_perception_mapany JSON value[]Required

Fields in source_perception_map

Array of any JSON value.

any JSON value.

competitor_narrativesobjectRequired

null

null.

PerceptionNarrativeDriftApiResponse

brand_idstringRequired

weeksintegerRequired

Minimum: 1 · Maximum: 52

driftobjectRequired

Fields in drift

historyobject[]Required

Fields in history

Array of object.

idstring | nullRequired

run_datestring | nullRequired

positioning_statementstringRequired

brand_tonestringRequired

primary_descriptorsany JSON value[]Required

Fields in primary_descriptors

Array of any JSON value.

any JSON value.

perception_scorenumberRequired

positioning_changedbooleanRequired

tone_changedbooleanRequired

new_descriptorsany JSON value[]Required

Fields in new_descriptors

Array of any JSON value.

any JSON value.

lost_descriptorsany JSON value[]Required

Fields in lost_descriptors

Array of any JSON value.

any JSON value.

diffobject | nullRequired

total_weeksintegerRequired

Minimum: 0

significant_changesintegerRequired

Minimum: 0

object

object. Additional keys are allowed.

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
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=dashboard and view=metrics read a period (400 otherwise); perception_score.change_period is the change against the prior period. See Periods.

Get Raw Metrics

Use view=metrics to get raw metric history data points. Each row contains all 20 metric scores for a specific tracked brand on a specific date. Useful for building custom charts.

Metrics View
curl -X GET 'https://api.trakkr.ai/get-perception?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=metrics&days=30&weeks=8' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Get Narrative

Use view=narrative to get a high-level positioning summary: how AI models describe your brand, key strengths, weaknesses, and emerging opportunities. The legacy sentiment_summary field remains in the response for compatibility and returns null.

Narrative View
curl -X GET 'https://api.trakkr.ai/get-perception?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=narrative&days=90&weeks=8' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
Response · 200 OK
{
  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
  "narrative": {
    "positioning": "Notion is consistently positioned as an all-in-one workspace that combines notes, docs, and project management. AI models describe it as a flexible productivity tool favored by teams and individuals.",
    "strengths": [
      "All-in-one workspace",
      "Flexible and customizable",
      "Strong template ecosystem",
      "AI-powered features",
      "Team collaboration"
    ],
    "weaknesses": [
      "Performance concerns",
      "Steep learning curve"
    ],
    "opportunities": [
      "AI integration leadership",
      "Enterprise adoption",
      "Offline capabilities"
    ],
    "sentiment_summary": null
  },
  "snapshot_date": "2026-03-20T14:30:00Z"
}

Synthetic example. Values are made up.

Weekly story

Use view=story to read the latest weekly story. The response contains brand_id andstory. When no weekly story is available,story is null. This view returns the latest story;days, weeks andtracked_brand do not filter it, andperiod is not supported.

A story includes its run date, prompt and response counts, written positioning, perception scores, descriptors, use cases, concerns, recommendations and cited sources. Scores may be null. Analysis lists and keyed values can vary, so check each entry before using it. The compatibility field narrative.tonealways returns an empty string; the written summary may also be empty.

Latest story
curl -X GET 'https://api.trakkr.ai/get-perception?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=story&days=90&weeks=8' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
No weekly story yet · 200 OK
{
  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
  "story": null
}

Synthetic example. Values are made up.

The response contract above lists the complete story fields. The playground uses made-up values to show the populated shape.

Narrative drift

Use view=narrative_drift for changes in the language models use about your brand. This view uses weeks, from 1 to 52, with a default of 8.days controls the dashboard and metrics views.

Narrative drift
curl -X GET 'https://api.trakkr.ai/get-perception?brand_id=00000000-0000-4000-8000-81f286d10c3c&view=narrative_drift&days=90&weeks=8' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"

Trigger Analysis

POST/get-perceptionTrigger a new perception analysis. Asks the perception AIs to evaluate your brand.

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

JSON request body (required)

brand_idstringRequired

Format: uuid

include_competitorsbooleanOptional

Default: true

Responses and errors
200Successful Response

application/json

statusstringRequired

brand_idstringRequired

primary_brandstring | nullOptional

run_datestring | nullOptional

brands_analyzedstring[]Optional

Default: []

Fields in brands_analyzed

Array of string. Default: []

string.

errorstring | nullOptional

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
Analysis asks the perception AIs to evaluate your brand. Completion time varies. Rate limited to 10 requests per minute. After triggering, use the GET endpoint to read the updated perception data once the analysis finishes.
Trigger Analysis
curl -X POST 'https://api.trakkr.ai/get-perception' \
  -H "Authorization: Bearer $TRAKKR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"brand_id":"00000000-0000-4000-8000-81f286d10c3c","include_competitors":true}'
Response · 200 OK
{
  "status": "success",
  "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
  "primary_brand": "Notion",
  "run_date": "2026-03-07",
  "brands_analyzed": ["Notion", "Coda", "Confluence", "Monday.com"],
  "error": null
}

Synthetic example. Values are made up.

The 20 Metrics

Each perception analysis evaluates 20 metrics on a 0-100 scale:

Trust & Reliability

overall_trust, reliability_score, transparency_level, safety_perception

Quality & Performance

overall_quality, problem_resolution, responsiveness, user_satisfaction

Value & Experience

value_for_money, ease_of_interaction, accessibility, necessity_level

Market Position

brand_recognition, professional_image, recommendation_likelihood, uniqueness

Innovation & Appeal

forward_thinking, adaptability, likability, confidence_inspiring

Quick Reference

EndpointDescriptionRate Limit
GET/get-perception
Dashboard, metrics, narrative, story and drift data60/min
POST/get-perception
Trigger new analysis10/min