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

# Narrative

> Editorial summary of the dominant storyline on a topic or watchlist, with sub-narrative weights and source diversity. Currently in alpha — actively shaping with design partners.

<Warning>
  **Narrative is in alpha.** The endpoint is live and stable enough to ship behind, but the **output format, summarisation depth, and per-customer tailoring** are actively evolving. We are deliberately keeping this surface flexible while we co-design it with the first wave of customers.

  If you have an opinion on how a narrative summary should read for **your** use case — newsroom desk-ready prose, SOC-grade incident framing, brand-risk tone, regulator-facing neutrality — **email [intel@exorde.io](mailto:intel@exorde.io)** and we will route your input directly into the roadmap. The customers who reach out now are the ones whose voice shapes the v1 contract.
</Warning>

The `narrative` endpoint returns an **editorial summary** of the dominant storyline on a topic or watchlist over the last rolling window, plus a structured breakdown of sub-narratives and their relative weights. Where [trending](/trending) gives you words and [alerts](/alerts) gives you events, narrative gives you the **story** — written in English by the editorial summarisation pipeline, ready to drop into a tile, a digest, or a brief.

| Surface               | Question                   | Shape                                     |
| --------------------- | -------------------------- | ----------------------------------------- |
| [Trending](/trending) | "Which words are spiking?" | Ranked list with z-scores                 |
| **Narrative**         | "What is the story?"       | Editorial summary + sub-narrative weights |
| [Alerts](/alerts)     | "What just happened?"      | Discrete events with severity             |

***

## What "alpha" means here

Concretely, today:

* **The endpoint shape is stable.** `summary`, `sub_narratives[]`, `data_freshness`, `snapshot_id` are the contract — these fields will not be removed without a major version bump. Build against them now.
* **The summary length, voice, and sectioning are evolving.** Today summaries are 1–3 sentences in a neutral editorial register. We are actively prototyping longer-form briefs, audience-tuned voices (newsroom / SOC / brand / regulator), and structured "what / who / where / why" breakdowns.
* **Per-customer tailoring is on the immediate roadmap.** Know-tier customers will be able to specify register, length, audience, and inclusion/exclusion preferences for the narrative on their own watchlists and private topics. **The shape of that configuration is being decided now**, with input from design-partner customers.
* **Historical narratives** (`/narratives/history`) are stable and unaffected by this alpha — that surface is See/Know-tier production.

If your team needs a specific output shape (a daily desk-ready brief, a SOC ticket-ready paragraph, a regulator-facing neutral synopsis), tell us and we will build for it. The design partner program is open and unpaid — you get early access to the tailored output, we get the requirements signal.

***

## The endpoints

| Endpoint                                    | Tier   | Returns                             | Status    |
| ------------------------------------------- | ------ | ----------------------------------- | --------- |
| `GET /v1/topics/{topic}/narrative`          | Watch+ | Latest narrative on a curated topic | **alpha** |
| `GET /v1/watchlists/{id}/narrative`         | See+   | Latest narrative on your watchlist  | **alpha** |
| `GET /v1/topics/{topic}/narratives/history` | See+   | Time-series of narrative shifts     | stable    |
| `GET /v1/topics/{topic}/narratives/posts`   | See+   | Source posts behind a narrative     | stable    |

This page covers the **latest narrative** endpoints. History and evidence are documented in [Topics and watchlists](/topics-and-watchlists#analytics-endpoints-on-curated-topics).

***

## The response envelope

```json theme={null}
{
  "topic": "global",
  "snapshot_id": "2026-05-19T13:00:00Z",
  "summary": "Regional escalation between Iran and Israel dominates global conversation, with overlapping ECB rate signal and Eurovision aftermath as secondary threads. Coverage spans Western news, regional Persian and Hebrew sources, and platform-native commentary.",
  "sub_narratives": [
    {
      "title": "Iran-Israel exchange",
      "weight": 0.61,
      "lead_terms": ["iran", "israel", "tehran", "idf"],
      "domain_count": 142,
      "language_count": 11
    },
    {
      "title": "ECB June pivot rumours",
      "weight": 0.22,
      "lead_terms": ["ecb", "lagarde", "rate cut"],
      "domain_count": 67,
      "language_count": 8
    },
    {
      "title": "Eurovision aftermath",
      "weight": 0.17,
      "lead_terms": ["eurovision", "winner", "voting"],
      "domain_count": 54,
      "language_count": 14
    }
  ],
  "source_diversity": { "domain_count": 263, "language_count": 21 },
  "data_freshness": { "snapshot_age_seconds": 312, "level": "ok" },
  "query_window": { "hours": 24, "effective_hours": 24 }
}
```

### Field guide

| Field                             | Stability                       | Meaning                                                |
| --------------------------------- | ------------------------------- | ------------------------------------------------------ |
| `topic` / `watchlist_id`          | stable                          | Scope identifier                                       |
| `snapshot_id`                     | stable                          | Pipeline run for reproducibility                       |
| `summary`                         | **alpha — wording evolving**    | Editorial-grade English, currently 1–3 sentences       |
| `sub_narratives[]`                | stable shape, **alpha titling** | Threads composing the dominant story                   |
| `sub_narratives[].title`          | **alpha — wording evolving**    | Short label suitable for a list item                   |
| `sub_narratives[].weight`         | stable                          | Fraction of the narrative volume (0.0–1.0, sums ≈ 1.0) |
| `sub_narratives[].lead_terms`     | stable                          | Top terms anchoring this sub-narrative                 |
| `sub_narratives[].domain_count`   | stable                          | Distinct source domains                                |
| `sub_narratives[].language_count` | stable                          | Distinct languages                                     |
| `source_diversity`                | stable                          | Aggregate breadth across all sub-narratives            |
| `data_freshness`                  | stable                          | Snapshot age + traffic-light level                     |

The **structural fields** (`weight`, `lead_terms`, `domain_count`, `language_count`, `source_diversity`) are the safe ones to build automation against today. The **prose fields** (`summary`, `sub_narratives[].title`) are where we expect the most evolution as we tailor for customers.

***

## Calling it

<CodeGroup>
  ```bash curl theme={null}
  curl https://intel-v1.exorde.io/v1/topics/global/narrative \
    -H "X-API-Key: $EXORDE_API_KEY"
  ```

  ```python Python theme={null}
  import os, httpx

  r = httpx.get(
      "https://intel-v1.exorde.io/v1/topics/global/narrative",
      headers={"X-API-Key": os.environ["EXORDE_API_KEY"]},
      timeout=10,
  ).json()

  print(r["summary"])
  print()
  for sub in r["sub_narratives"]:
      print(f"  {sub['weight']:>5.1%}  {sub['title']}")
      print(f"          terms: {', '.join(sub['lead_terms'][:4])}")
      print(f"          spread: {sub['domain_count']}d × {sub['language_count']}l")
  ```

  ```javascript Node theme={null}
  const r = await fetch(
    "https://intel-v1.exorde.io/v1/topics/global/narrative",
    { headers: { "X-API-Key": process.env.EXORDE_API_KEY } }
  ).then(r => r.json());

  console.log(r.summary);
  r.sub_narratives.forEach(s =>
    console.log(`  ${(s.weight * 100).toFixed(1)}%  ${s.title}`)
  );
  ```

  ```powershell PowerShell theme={null}
  $r = Invoke-RestMethod `
    -Uri "https://intel-v1.exorde.io/v1/topics/global/narrative" `
    -Headers @{ "X-API-Key" = $env:EXORDE_API_KEY }

  $r.summary
  $r.sub_narratives | Select-Object weight, title, domain_count, language_count | Format-Table
  ```
</CodeGroup>

***

## Reading the response

### `summary`

Plain English, neutral register, **drop straight into a Slack tile or email digest**. Today's summaries are 1–3 sentences. They are designed to be readable by a non-technical reader (an exec, a comms lead, a duty editor) without context.

Do **not** parse the summary in code. Treat it as an opaque string. If your application needs structured fields (entities mentioned, sentiment, geography), use the `sub_narratives[]` breakdown or pivot into [entities](/topics-and-watchlists#analytics-endpoints-on-curated-topics) and [clusters](/topics-and-watchlists#analytics-endpoints-on-curated-topics).

### `sub_narratives[]`

The dominant story is rarely monolithic — it's usually composed of 2–5 threads with different emphases. `sub_narratives[]` exposes those threads with weights summing to roughly 1.0. Use them to:

* power a "what's in the mix" expandable on a dashboard,
* detect a pivot (a thread's weight jumping snapshot-over-snapshot),
* route to the right team (an Iran-Israel sub-narrative on `global` goes to the foreign desk; an ECB sub-narrative goes to the markets desk).

### `source_diversity`

The breadth of the conversation. A narrative with 263 domains and 21 languages is a genuinely global story; one with 12 domains and 2 languages is regional or niche. Useful as a filter for "is this worth surfacing to leadership."

***

## Cadence

Narrative regenerates on the same snapshot cadence as trending — every few minutes. The summarisation step is more expensive than ranking, so individual narrative responses may lag a snapshot or two behind trending under heavy load. `data_freshness.snapshot_age_seconds` always reflects the actual age of the data backing this narrative.

| Use case            | Tier       | Cadence                        |
| ------------------- | ---------- | ------------------------------ |
| Dashboard tile      | Watch      | every 5 min                    |
| Hourly exec digest  | See        | every 60 min                   |
| Daily desk brief    | See / Know | every 24h                      |
| Real-time wallboard | Know       | every 5 min (snapshot cadence) |

Polling faster than the snapshot cadence is wasted RPM. See [Rate limits](/rate-limits).

***

## Narrative on a watchlist

Same shape, scoped to your watchlist's terms. Particularly useful for **brand and risk monitoring** — the narrative around your scope often diverges from the topic baseline.

```bash theme={null}
curl https://intel-v1.exorde.io/v1/watchlists/wl_01HXYZ.../narrative \
  -H "X-API-Key: $EXORDE_API_KEY"
```

A real example on an `acme-monitoring` watchlist might surface a sub-narrative around an executive announcement that is invisible at the `global` level — exactly the kind of "what is *my* story" view that benefits most from per-customer voice tailoring.

***

## Historical narratives (stable surface)

`/v1/topics/{topic}/narratives/history` returns the time-series of narrative shifts — when sub-narratives entered, peaked, and faded. Same envelope shape as the latest endpoint, plus a `narratives[]` array indexed by snapshot. Available See+ and **not in alpha** — the contract is stable. See [Topics and watchlists](/topics-and-watchlists#analytics-endpoints-on-curated-topics).

***

## Roadmap and how to influence it

The shortlist of items actively under design, in priority order:

1. **Audience-tuned voice.** Per-key configuration of register: `editorial`, `analyst`, `executive`, `regulator`. Same data, different tone.
2. **Per-customer brief format.** Optional structured sections (`what`, `who`, `where`, `why_it_matters`) for customers building automated briefs.
3. **Length controls.** `concise` (1 sentence), `default` (1–3), `brief` (paragraph), `report` (multi-paragraph with sub-headers).
4. **Inclusion/exclusion lexicons.** Customer-specific stopwords and "always mention if present" terms baked into summarisation.
5. **Narrative deltas.** A `vs_previous_snapshot` field describing what changed — "ECB pivot rumours overtook Eurovision as the second-largest thread."
6. **Multi-language summaries.** French, German, Spanish, Arabic native summaries — not translations.

**This list is not fixed.** It will move based on what design-partner customers ask for. If your priority isn't here, [tell us](mailto:intel@exorde.io) — we are explicitly looking for the use cases we haven't seen yet.

### How to engage

* **Email [intel@exorde.io](mailto:intel@exorde.io)** with one paragraph: who you are, what scope you'd use narrative on, what shape of output would make it indispensable for your workflow.
* **Or book a 30-minute design call** via the same address — we run these weekly with prospective design partners.
* **Or just send the JSON shape you wish you got back** and we'll tell you whether and when we can ship it.

The earliest customers shape the contract. Once we lock v1, the surface stabilises and tailoring moves behind a "preference profile" rather than a co-design conversation.

***

## Operational guidance

* **Don't parse `summary`.** It's prose, not structured data. Use `sub_narratives[].title` and `lead_terms` for structured logic.
* **Watch `weight` shifts** snapshot-over-snapshot to detect narrative pivots — often the most valuable signal narrative gives you.
* **Pair with [trending](/trending)** for full state coverage: trending shows the spike, narrative shows the story it composes.
* **Pair with [alerts](/alerts)** for full event coverage: an alert is the moment a sub-narrative is born; narrative is what it grew into 30 minutes later.
* **Cite `snapshot_id`** in any downstream artefact (brief, ticket, dashboard) so the analysis is reproducible if the narrative shifts.
* **Build against structural fields first** — given the alpha status of the prose, automation that depends on `weight`, `lead_terms`, `domain_count` is more durable today than automation that depends on `summary` wording.

***

## Errors specific to narrative

| Status | `error`                 | When                                                                                                               |
| ------ | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| 404    | `narrative_unavailable` | The pipeline hasn't yet produced a narrative for this scope (very low-volume watchlists or freshly-created scopes) |
| 410    | `snapshot_expired`      | Pinned `snapshot_id` is past retention — refetch latest                                                            |
| 503    | `service_unavailable`   | Summarisation pipeline degraded — retry with backoff                                                               |

Full error envelope: [Errors](/errors).

***

## What's not narrative

| You want                              | Use this                                   |
| ------------------------------------- | ------------------------------------------ |
| "What words are spiking"              | [Trending](/trending)                      |
| "Posts behind this narrative"         | `/v1/topics/{t}/narratives/posts` (See+)   |
| "How the narrative shifted over time" | `/v1/topics/{t}/narratives/history` (See+) |
| "Editorial weekly intelligence brief" | `/v1/topics/{t}/reports/latest` (Know)     |
| "Push me when something just broke"   | [Alerts](/alerts)                          |

Narrative is the **state-of-the-story** view at a snapshot. Reports are deeper, scheduled, editorial. Alerts are the events that compose it.

<Note>Last reviewed: 2026-05-19. API version 1.2.8. **`summary` and `sub_narratives[].title` wording in alpha — actively shaped by design-partner feedback.**</Note>