> This page is for version v1.0.1 (default).
> For other versions, use one of these documentation indexes:
> - v1.0.1 (default): https://docs.kinetk.ai/v-1-0-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kinetk.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kinetk.ai/_mcp/server.

# Narrative Intelligence

> What a narrative is, and how to read trending, search, detail and trajectory from the narrative map.

A **narrative** is a group of posts built around a shared idea, such as a topic, framing or moment that a community is talking about. KINETK tracks each narrative over time, so you can see it grow, spread across platforms and change in tone.

All narrative reads are **free** and return in under 3 seconds. They take `window=7d` (rebuilt every 6 hours, the default) or `window=30d` (rebuilt daily). For an all-time or custom analysis, run an [`insights` job](/documentation/guides/intelligence-jobs).

> **Note**
>
> Narratives follow **what people are talking about**. [Patterns](/documentation/guides/pattern-intelligence) follow **what content looks like**.

## Trending

```http
GET /narratives/trending?window=7d&limit=12
```

#### cURL

```bash
curl -H "x-api-key: $API_KEY" "$API_BASE/narratives/trending?window=7d&limit=12"
```

Returns the top narratives for the window (`limit` 1–100, default 20):

```json
{
  "window": "7d",
  "narratives": [
    {
      "id": "4182",
      "label": "Smartwatch fitness accountability",
      "summary": "Creators pairing smartwatch reviews with community accountability challenges…",
      "momentum_score": 0.74,
      "emerging_score": 0.82,
      "content_count": 1240,
      "creator_count": 316,
      "platform_count": 4,
      "total_engagement": "18240501",
      "top_tags": ["smartwatch", "fitness", "accountability"],
      "lifecycle": "growing",
      "sentiment_label": "positive"
    }
  ]
}
```

* `momentum_score`: how fast it's moving. `emerging_score`: how new it is.
* `lifecycle`: `emerging`, `growing`, `peaking` or `declining`. `null` for narratives too new to have history.
* `sentiment_label`: the overall tone of its posts.
* `total_engagement` is a string, because it can exceed JavaScript's safe integer range.

> **Warning**
>
> Narrative names can change between rebuilds. Store the `id`, never the `label`.

## Search

```http
GET /narratives/search?q=smart+watch&window=7d
```

#### cURL

```bash
curl -H "x-api-key: $API_KEY" "$API_BASE/narratives/search?q=smart+watch&window=7d"
```

Finds narratives whose name or tags contain every word of `q`. If none match, it falls back to narratives whose posts mention the query, then to trending. Returns the same rows as trending.

## One narrative

```http
GET /narratives/4182
```

#### cURL

```bash
curl -H "x-api-key: $API_KEY" "$API_BASE/narratives/4182"
```

Returns the narrative plus its evidence:

* `content[]`: its posts, with engagement counts.
* `creators[]`: its top creators.
* `platformBreakdown[]`: posts and engagement per platform.

You get narrative ids from trending, search, the `narrativeIds` on `POST /search` results, and the `persistentLink` on `insights` results.

## Trajectory

```http
GET /narratives/4182/trajectory
```

#### cURL

```bash
curl -H "x-api-key: $API_KEY" "$API_BASE/narratives/4182/trajectory"
```

Returns the narrative's metrics at each rebuild, newest first (`limit` 1–200, default 60): momentum, size, engagement, sentiment and `lifecycle`. Use it to tell whether a narrative is accelerating or fading.