> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfacd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports API: Narratives

> The narratives entity - the Reputation overview, narratives, themes and competitor reports.

`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](/docs/reports-api) page first for the request shape, filter roles and the compare window, and [Reputation](/docs/reputation) for what narratives and themes are.

<Note>
  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`.
</Note>

## 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`.

## Related blocks

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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](/docs/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.

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

```json theme={null}
{
  "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](/docs/reports-api-sources):

```json theme={null}
{
  "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](/docs/reports-api-visibility#answer-rows):

```json theme={null}
{
  "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

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

### Theme × platform matrix

```json theme={null}
{
  "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](/docs/reputation-competitors) view: every tracked brand side by side.

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

### Competitor × theme matrix

```json theme={null}
{
  "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
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.