Skip to navigation
Guides

Narrative Intelligence

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.

Narratives follow what people are talking about. Patterns follow what content looks like.

GET /narratives/trending?window=7d&limit=12
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):

{
  "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.

Narrative names can change between rebuilds. Store the id, never the label.

GET /narratives/search?q=smart+watch&window=7d
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

GET /narratives/4182
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

GET /narratives/4182/trajectory
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.