Reports API: Narratives

POST /api/v1/projects/{project}/reports/narratives One row per reputation narrative, theme, brand or narrative sentiment, or per platform, country, topic, tag, prompt or time bucket. Read the Reports API page first for the request shape, filter roles and the compare window, and Reputation for what narratives and themes are.

The narratives entity, and the carries_narrative and carries_theme filters on any entity, need the Reputation feature on the project’s team. Without it the request returns 403.

Dimensions

id	Row	Label columns
`narrative`	One row per narrative, zero-filled when nothing carried it in the window	`narrative`, `narrative_uuid`
`theme`	Per theme	`theme`, `theme_uuid`
`brand`	Per tracked brand the narratives are about	`brand`, `brand_uuid`
`narrative_sentiment`	The narrative’s fixed polarity	`positive`, `negative`
`service`, `country`, `tag`, `topic`, `prompt`, `date`, `week`, `month`	As on visibility

Measures

id	Meaning	Unit
`answers`	Answers in the group that carry a narrative	count
`share`	`answers` as a share of all answers in the population, the ”% of responses” on the Reputation pages	decimal, `percent`
`mentions`	Narrative mentions in the group. An answer can carry several.	count
`narratives`	Distinct narratives in the group	count
`sentiment`	Net Sentiment Index of the group’s mentions	0 to 100
`positive`, `neutral`, `negative`	Mentions by sentiment, the composition bar	count
`rank`	Position by `answers` within the group. Assigned before row filters.	integer

Two sentiments can sit on one row. narrative_sentiment is the narrative’s fixed polar label; sentiment is the index of its mentions in the window.

Filters

Population fields as on the main page.
narrative, theme, brand and narrative_sentiment are entity fields: in and not_in with UUIDs (or the sentiment words), contains on the label. Each needs its dimension on the row. narrative contains "pricing" is the narratives search box.
Measures take comparisons: share gte 0.05, share_change lte -0.02.

Both need narrative on the row.

id	Per row
`narrative_description`	The narrative’s description, as `description`
`evidence`	Up to five of the newest mentions in the window: `{ "answer_uuid", "answered_at", "brand", "sentiment", "snippet" }`

Reputation overview

KPIs and the composition bar

Answers carrying a narrative about your brand, their share, the narrative count, the sentiment index and the positive / neutral / negative split, with trends. benchmarks[0] carries the trend of the first measure.

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": ["brand"],
  "measures": ["answers", "share", "narratives", "sentiment", "positive", "neutral", "negative"],
  "filters": [{ "field": "brand", "op": "in", "values": ["BRAND_UUID"] }]
}

Sentiment over time

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["brand", "date"],
  "measures": ["answers", "share", "sentiment", "positive", "neutral", "negative"],
  "filters": [{ "field": "brand", "op": "in", "values": ["BRAND_UUID"] }],
  "order_by": [{ "field": "date", "dir": "asc" }],
  "limit": 1000
}

Sentiment by model

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["brand", "service"],
  "measures": ["answers", "share", "sentiment", "positive", "neutral", "negative"],
  "filters": [{ "field": "brand", "op": "in", "values": ["BRAND_UUID"] }]
}

Narratives

The narratives list with movers

The Themes & Narratives list for your brand, with the previous period for the movers. share_change is the movement. Drop brand from dimensions to get every narrative zero-filled across brands, so one that vanished this period still shows with its compare value.

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "compare_start_date": "2026-08-04",
  "compare_end_date": "2026-08-31",
  "dimensions": ["narrative", "narrative_sentiment", "theme", "brand"],
  "measures": ["answers", "share", "sentiment"],
  "filters": [{ "field": "brand", "op": "in", "values": ["BRAND_UUID"] }],
  "related": ["narrative_description"],
  "order_by": [{ "field": "share", "dir": "desc" }]
}

The page’s filters map directly:

Filter in the app	Add to `filters`
Sentiment	`{ "field": "narrative_sentiment", "op": "in", "values": ["negative"] }`
Theme	`{ "field": "theme", "op": "in", "values": ["THEME_UUID"] }`
Search	`{ "field": "narrative", "op": "contains", "value": "pricing" }`

Negative narratives across every brand

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["narrative", "narrative_sentiment", "theme"],
  "measures": ["answers", "share", "mentions", "rank"],
  "filters": [{ "field": "narrative_sentiment", "op": "in", "values": ["negative"] }],
  "limit": 50
}

Narrative evidence

The newest snippets under each narrative.

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["narrative", "brand"],
  "measures": ["answers", "mentions"],
  "filters": [{ "field": "brand", "op": "in", "values": ["BRAND_UUID"] }],
  "related": ["narrative_description", "evidence"],
  "limit": 10
}

A narrative’s Sources and Responses tabs

The narrative detail page reads other entities inside that narrative’s answers. carries_narrative is a population filter available on every entity; mentions_brand scopes it to narratives about your brand. Find the narrative UUID with GET /api/v1/projects/{project}/reports/values/carries_narrative?search=pricing. Sources tab, on the sources entity:

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["domain"],
  "measures": ["citations", "responses", "answers", "share"],
  "filters": [
    { "field": "mentions_brand", "op": "in", "values": ["BRAND_UUID"] },
    { "field": "carries_narrative", "op": "in", "values": ["NARRATIVE_UUID"] }
  ],
  "limit": 25
}

Responses tab, on visibility answer rows:

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["answer", "service", "prompt"],
  "measures": ["mentions", "citations"],
  "filters": [
    { "field": "mentions_brand", "op": "in", "values": ["BRAND_UUID"] },
    { "field": "carries_narrative", "op": "in", "values": ["NARRATIVE_UUID"] }
  ],
  "order_by": [{ "field": "answered_at", "dir": "desc" }],
  "related": ["answer_text"],
  "limit": 25
}

carries_theme does the same for a whole theme.

Themes

The themes list

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["theme"],
  "measures": ["answers", "share", "narratives", "sentiment"]
}

Theme × platform matrix

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["theme", "service"],
  "measures": ["answers", "share", "sentiment"],
  "order_by": [{ "field": "theme", "dir": "asc" }, { "field": "service", "dir": "asc" }],
  "limit": 1000
}

Competitors

Brands compared

The Reputation Competitors view: every tracked brand side by side.

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["brand"],
  "measures": ["answers", "share", "narratives", "sentiment", "positive", "negative"]
}

Competitor × theme matrix

{
  "start_date": "2026-09-01",
  "end_date": "2026-09-28",
  "dimensions": ["brand", "theme"],
  "measures": ["answers", "share", "sentiment"],
  "order_by": [{ "field": "brand", "dir": "asc" }, { "field": "theme", "dir": "asc" }],
  "limit": 1000
}

Getting Started

Projects

Reports & Analysis

Reputation

API & MCP

Account

Reports API: Narratives

Dimensions

Measures

Filters

Reputation overview

KPIs and the composition bar

Sentiment over time

Sentiment by model

Narratives

The narratives list with movers

Negative narratives across every brand

Narrative evidence

A narrative’s Sources and Responses tabs

Themes

The themes list

Theme × platform matrix

Competitors

Brands compared

Competitor × theme matrix

​Dimensions

​Measures

​Filters

​Related blocks

​Reputation overview

​KPIs and the composition bar

​Sentiment over time

​Sentiment by model

​Narratives

​The narratives list with movers

​Negative narratives across every brand

​Narrative evidence

​A narrative’s Sources and Responses tabs

​Themes

​The themes list

​Theme × platform matrix

​Competitors

​Brands compared

​Competitor × theme matrix

Dimensions

Measures

Filters

Related blocks

Reputation overview

KPIs and the composition bar

Sentiment over time

Sentiment by model

Narratives

The narratives list with movers

Negative narratives across every brand

Narrative evidence

A narrative’s Sources and Responses tabs

Themes

The themes list

Theme × platform matrix

Competitors

Brands compared

Competitor × theme matrix