Narratives

Track how AI models discuss specific topics about your brand. Full CRUD with snapshot history and corrective tracking.

Requires authentication

60 req/min

Overview

Narratives let you track how AI models discuss specific topics related to your brand. Each narrative monitors keywords across AI models and produces periodic snapshots showing scores, themes, and whether your corrective content is being reflected.

Narratives require the Scale plan. You can have up to 5 active narratives per brand. Archiving a narrative frees up the slot.

List Narratives

GET/narrativesList all narratives for a brand, or get a single narrative by ID.

Query Parameters

brand_idstringrequired

The brand ID to list narratives for

narrative_idstring

Get a single narrative by ID (detail view)

includestring

Comma-separated: "snapshots", "correctives"

daysinteger

Days of snapshot history to include (7-365)

Default: 90

The Narrative Object

Narrative Schema

idstring

Unique narrative identifier

brand_idstring

The brand this narrative belongs to

namestring

Narrative name

descriptionstring

What this narrative tracks

keywordsstring[]

Keywords being monitored

comparison_brandstringnullable

Comparison brand (if set)

statusstring

"critical", "active", "monitoring", or "resolved"

created_atstring

ISO 8601 creation timestamp

latest_snapshotobjectnullable

Most recent analysis snapshot

correctivesarraynullable

Published corrective messages (when include=correctives)

snapshotsarraynullable

Snapshot history (when include=snapshots)

Create Narrative

POST/narrativesCreate a new narrative. First analysis runs automatically in the background.

Body Parameters

brand_idstringrequired

The brand ID

namestringrequired

Narrative name (1-200 chars)

descriptionstringrequired

What this narrative tracks (1-2000 chars)

keywordsstring[]required

Keywords to monitor (1-10 items)

comparison_brandstring

Optional brand to compare against

Create Narrative

1curl -X POST 'https://api.trakkr.ai/narratives' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "brand_id": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
6    "name": "Product Quality Perception",
7    "description": "How AI models describe our product quality vs competitors",
8    "keywords": ["quality", "reliability", "performance"],
9    "comparison_brand": "Competitor Inc"
10  }'

200 OK

1{
2  "narrative_id": "narr_abc123",
3  "status": "created",
4  "message": "Narrative created and first analysis started"
5}

Update Narrative

PATCH/narrativesUpdate a narrative's name, description, keywords, or status.

Body Parameters

narrative_idstringrequired

The narrative ID to update

namestring

Updated name

descriptionstring

Updated description

keywordsstring[]

Updated keywords

comparison_brandstring

Updated comparison brand

statusstring

Status: "critical", "active", "monitoring", "resolved"

Update Narrative

1curl -X PATCH 'https://api.trakkr.ai/narratives' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "narrative_id": "narr_abc123",
6    "name": "Updated Narrative Name",
7    "status": "monitoring"
8  }'

Archive Narrative

DELETE/narrativesArchive (soft-delete) a narrative. Sets status to resolved.

Pass the narrative_id as a query parameter. Archived narratives are excluded from the active limit count.

Archive Narrative

1curl -X DELETE 'https://api.trakkr.ai/narratives?narrative_id=narr_abc123' \
2  -H 'Authorization: Bearer $TRAKKR_API_KEY'

Quick Reference

Endpoint	Description	Rate Limit
GET`/narratives`	List or get narrative	60/min
POST`/narratives`	Create narrative	10/min
PATCH`/narratives`	Update narrative	30/min
DELETE`/narratives`	Archive narrative	30/min

Code Example

List Narratives

1curl -H 'Authorization: Bearer $TRAKKR_API_KEY' \
2  'https://api.trakkr.ai/narratives?brand_id=YOUR_BRAND_ID&include=correctives'

200 OK

1{
2  "narratives": [
3    {
4      "id": "narr_abc123",
5      "brand_id": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
6      "name": "Product Quality Perception",
7      "description": "How AI models describe our product quality vs competitors",
8      "keywords": ["quality", "reliability", "performance"],
9      "comparison_brand": "Competitor Inc",
10      "status": "active",
11      "created_at": "2026-02-15T10:30:00Z",
12      "latest_snapshot": {
13        "id": "snap_xyz789",
14        "run_date": "2026-03-01",
15        "run_type": "weekly",
16        "overall_score": 72.5,
17        "summary": "AI models consistently describe Notion as high-quality...",
18        "comparison_score": 65.0,
19        "themes": [
20          {"theme": "reliability", "sentiment": "positive", "count": 3}
21        ]
22      },
23      "correctives": [
24        {
25          "id": "corr_001",
26          "name": "Q1 Product Launch Blog",
27          "key_phrases": ["new features", "reliability improvements"],
28          "url": "https://blog.notion.com/q1-launch",
29          "published_at": "2026-01-15"
30        }
31      ]
32    }
33  ]
34}

List Narratives

1curl -H 'Authorization: Bearer $TRAKKR_API_KEY' \
2  'https://api.trakkr.ai/narratives?brand_id=YOUR_BRAND_ID&include=correctives'

200 OK

1{
2  "narratives": [
3    {
4      "id": "narr_abc123",
5      "brand_id": "75ffdeb9-0924-4ff9-8ded-c2470d73d224",
6      "name": "Product Quality Perception",
7      "description": "How AI models describe our product quality vs competitors",
8      "keywords": ["quality", "reliability", "performance"],
9      "comparison_brand": "Competitor Inc",
10      "status": "active",
11      "created_at": "2026-02-15T10:30:00Z",
12      "latest_snapshot": {
13        "id": "snap_xyz789",
14        "run_date": "2026-03-01",
15        "run_type": "weekly",
16        "overall_score": 72.5,
17        "summary": "AI models consistently describe Notion as high-quality...",
18        "comparison_score": 65.0,
19        "themes": [
20          {"theme": "reliability", "sentiment": "positive", "count": 3}
21        ]
22      },
23      "correctives": [
24        {
25          "id": "corr_001",
26          "name": "Q1 Product Launch Blog",
27          "key_phrases": ["new features", "reliability improvements"],
28          "url": "https://blog.notion.com/q1-launch",
29          "published_at": "2026-01-15"
30        }
31      ]
32    }
33  ]
34}