Skip to content
TrakkrLearnAPI
Sign in

Narratives

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

Code example

List Narratives
curl -X GET 'https://api.trakkr.ai/narratives?brand_id=00000000-0000-4000-8000-81f286d10c3c&include=correctives&days=90' \
  -H "Authorization: Bearer $TRAKKR_API_KEY"
Response · 200 OK
{
  "narratives": [
    {
      "id": "narr_abc123",
      "brand_id": "00000000-0000-4000-8000-81f286d10c3c",
      "name": "Product Quality Perception",
      "description": "How AI models describe our product quality vs competitors",
      "keywords": ["quality", "reliability", "performance"],
      "comparison_brand": "Competitor Inc",
      "status": "active",
      "created_at": "2026-02-15T10:30:00Z",
      "latest_snapshot": {
        "id": "snap_xyz789",
        "run_date": "2026-03-01",
        "run_type": "weekly",
        "overall_score": 72.5,
        "summary": "AI models consistently describe Notion as high-quality...",
        "comparison_score": 65.0,
        "themes": [
          {"theme": "reliability", "sentiment": "positive", "count": 3}
        ]
      },
      "correctives": [
        {
          "id": "corr_001",
          "name": "Q1 Product Launch Blog",
          "key_phrases": ["new features", "reliability improvements"],
          "url": "https://blog.notion.com/q1-launch",
          "published_at": "2026-01-15"
        }
      ]
    }
  ]
}

Synthetic example. Values are made up.

API key required

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 10 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.

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

Request parameters

brand_idstringqueryRequired

Brand UUID

Format: uuid

narrative_idstring | nullqueryOptional

Specific narrative ID for detail view

includestring | nullqueryOptional

Comma-separated: snapshots,correctives

daysintegerqueryOptional

Days for snapshot history

Default: 90 · Minimum: 7 · Maximum: 365

Responses and errors
200Successful Response

application/json

NarrativesListApiResponse

narrativesobject[]Required

Fields in narratives

Array of object.

idstringRequired

brand_idstringRequired

namestringRequired

descriptionstringRequired

keywordsstring[]Optional

Default: []

Fields in keywords

Array of string. Default: []

string.

comparison_brandstring | nullOptional

statusstringRequired

created_atstringRequired

latest_snapshotobject | nullOptional

Fields in latest_snapshot
NarrativeSnapshotApi

idstringRequired

run_datestringRequired

run_typestringRequired

overall_scorenumber | nullOptional

summarystring | nullOptional

comparison_scorenumber | nullOptional

themesobject[] | nullOptional

null

null.

correctivesobject[] | nullOptional

snapshotsobject[] | nullOptional

NarrativeItemApi

idstringRequired

brand_idstringRequired

namestringRequired

descriptionstringRequired

keywordsstring[]Optional

Default: []

Fields in keywords

Array of string. Default: []

string.

comparison_brandstring | nullOptional

statusstringRequired

created_atstringRequired

latest_snapshotobject | nullOptional

Fields in latest_snapshot
NarrativeSnapshotApi

idstringRequired

run_datestringRequired

run_typestringRequired

overall_scorenumber | nullOptional

summarystring | nullOptional

comparison_scorenumber | nullOptional

themesobject[] | nullOptional

null

null.

correctivesobject[] | nullOptional

snapshotsobject[] | nullOptional

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source

Create Narrative

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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

JSON request body (required)

brand_idstringRequired

Format: uuid

namestringRequired

Minimum length: 1 · Maximum length: 200

descriptionstringRequired

Minimum length: 1 · Maximum length: 2000

keywordsstring[]Required

Minimum items: 1 · Maximum items: 10

Fields in keywords

Array of string. Minimum items: 1 · Maximum items: 10

string.

comparison_brandstring | nullOptional

Responses and errors
200Successful Response

application/json

narrative_idstringRequired

statusstringOptional

Default: "created"

messagestringOptional

Default: "Narrative created and first analysis started"

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source
Create Narrative
curl -X POST 'https://api.trakkr.ai/narratives' \
  -H "Authorization: Bearer $TRAKKR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"brand_id":"00000000-0000-4000-8000-81f286d10c3c","name":"Product Quality Perception","description":"How AI models describe our product quality vs competitors","keywords":["quality","reliability","performance"],"comparison_brand":"Competitor Inc"}'
Response · 200 OK
{
  "narrative_id": "narr_abc123",
  "status": "created",
  "message": "Narrative created and first analysis started"
}

Synthetic example. Values are made up.

Update Narrative

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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

JSON request body (required)

narrative_idstringRequired

namestring | nullOptional

Minimum length: 1 · Maximum length: 200

descriptionstring | nullOptional

Minimum length: 1 · Maximum length: 2000

keywordsstring[] | nullOptional

Minimum items: 1 · Maximum items: 10

comparison_brandstring | nullOptional

statusstring | nullOptional

Responses and errors
200Successful Response

application/json

narrative_idstringRequired

statusstringOptional

Default: "updated"

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source
Update Narrative
curl -X PATCH 'https://api.trakkr.ai/narratives' \
  -H "Authorization: Bearer $TRAKKR_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"narrative_id":"narr_abc123","name":"Updated Narrative Name","status":"monitoring"}'

Archive Narrative

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

Authenticate with Authorization: Bearer $TRAKKR_API_KEY. Key and access guide

Request parameters

narrative_idstringqueryRequired

Narrative ID to archive

Responses and errors
200Successful Response

application/json

narrative_idstringRequired

statusstringOptional

Default: "archived"

401Missing, malformed, or expired credentials

application/json

detailstring | object | nullOptional

errorstring | nullOptional

402The current plan does not fund this operation

application/json

detailstring | object | nullOptional

errorstring | nullOptional

403Invalid credentials, missing brand access, or insufficient role

application/json

detailstring | object | nullOptional

errorstring | nullOptional

422Validation Error

application/json

detailobject[]Optional

Fields in detail

Array of object.

locstring | integer[]Required

Fields in loc

Array of string | integer.

string

string.

integer

integer.

msgstringRequired

typestringRequired

429Rate limit exceeded

application/json

detailstring | object | nullOptional

errorstring | nullOptional

500The operation failed

application/json

detailstring | object | nullOptional

errorstring | nullOptional

503Authentication, entitlement, or a required dependency is temporarily unavailable

application/json

detailstring | object | nullOptional

errorstring | nullOptional

OpenAPI source

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

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

Quick Reference

EndpointDescriptionRate Limit
GET/narratives
List or get narrative60/min
POST/narratives
Create narrative10/min
PATCH/narratives
Update narrative30/min
DELETE/narratives
Archive narrative30/min