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

# Example Workflows

> Common narrative intelligence use cases utilizing the PeakMetrics API

## 1. Brand Sentiment Tracking

### Overview

Track how favorability discourse changes over time using a Smart Category.
This workflow helps you understand nuanced sentiment shifts tailored to your brand.

### Prerequisites

* A workspace configured with a "Favorability" Smart Category

### Step-by-Step Guide

1. **Discover Smart Category Configuration**
   Query the filters endpoint to find your Smart Category enrichment\_id and available classifications.

2. **Get Current Favorability Breakdown**
   Use the distribution endpoint to see the current favorability mix across all classifications.

3. **Track Favorability Over Time**
   Use timeline analytics with `group_by` set to the Smart Category enrichment\_id
   to see how all favorability classifications evolve over time in a single request.

### Example Requests

#### Step 1: Find Smart Category Enrichment ID

```bash theme={null}
GET /workspaces/123/available-filters
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
{
  "smart_categories": {
    "models": [
      {
        "name": "Favorability",
        "enrichment_id": 244,
        "options": [
          {"name": "Favorable", "value": "244:c0"},
          {"name": "Unfavorable", "value": "244:c1"},
          {"name": "Neutral", "value": "244:c2"},
          {"name": "Not Applicable", "value": "244:c3"}
        ]
      }
    ]
  }
}
```

#### Step 2: Get Current Distribution

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=smart_category_enrichment_id:244&since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "groupBy": "smart_category_enrichment_id:244",
  "totalCount": 50000,
  "groups": [
    {"key": "c0", "name": "Favorable", "count": 20000, "percentage": 40.0},
    {"key": "c1", "name": "Unfavorable", "count": 15000, "percentage": 30.0},
    {"key": "c2", "name": "Neutral", "count": 10000, "percentage": 20.0},
    {"key": "c3", "name": "Not Applicable", "count": 5000, "percentage": 10.0}
  ]
}
```

#### Step 3: Track Favorability Over Time

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&group_by=smart_category_enrichment_id:244
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
{
  "totalCount": 50000,
  "buckets": [
    {
      "date": "2025-01-01T00:00:00Z",
      "count": 1500,
      "groups": [
        {"key": "c0", "count": 600},
        {"key": "c1", "count": 450},
        {"key": "c2", "count": 300},
        {"key": "c3", "count": 150}
      ]
    },
    {
      "date": "2025-01-02T00:00:00Z",
      "count": 1600,
      "groups": [
        {"key": "c0", "count": 640},
        {"key": "c1", "count": 480},
        {"key": "c2", "count": 320},
        {"key": "c3", "count": 160}
      ]
    }
  ]
}
```

### Analysis Tips

* Use the `groups` array in each timeline bucket to see the breakdown of all
  favorability classifications for that day
* Compare favorability classification counts across time buckets to identify
  shifts (e.g., increasing "Favorable" counts)
* Calculate percentages within each bucket:
  `(classification_count / bucket_count) * 100` to see daily favorability mix
* Track "Favorable" (c0) to see overall positive sentiment trends
* Monitor "Unfavorable" (c1) separately to identify critical reputation issues
* Use the timeline data to correlate favorability changes with specific events or campaigns

***

## 2. Bot Detection Analysis

### Overview

Assess how much bots are driving the conversation and identify what narratives
bots are pushing. This workflow helps you understand the authenticity of
discourse and detect coordinated inauthentic behavior.

### Prerequisites

* A workspace that includes social media channels

### Step-by-Step Guide

1. **Assess Overall Bot Presence**
   Get distribution by bot ratings to see the overall bot landscape.

2. **Identify High-Confidence Bots**
   Filter to high-confidence bot ratings to focus on likely automated accounts.

3. **Analyze Bot-Driven Mentions**
   Retrieve mentions from high-confidence bots to understand their messaging.

4. **Identify Bot Narratives**
   Examine which narratives bots are amplifying by filtering mentions by narrative IDs.

### Example Requests

#### Step 1: Get Bot Rating Distribution

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=bot_ratings&since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "groupBy": "bot_ratings",
  "totalCount": 100000,
  "groups": [
    {"key": "almost_certain", "name": "Almost Certain", "count": 5000, "percentage": 5.0},
    {"key": "very_likely", "name": "Very Likely", "count": 8000, "percentage": 8.0},
    {"key": "likely", "name": "Likely", "count": 12000, "percentage": 12.0},
    {"key": "potential", "name": "Potential", "count": 15000, "percentage": 15.0},
    {"key": "unlikely", "name": "Unlikely", "count": 25000, "percentage": 25.0},
    {"key": "very_unlikely", "name": "Very Unlikely", "count": 20000, "percentage": 20.0},
    {"key": "none", "name": "None", "count": 15000, "percentage": 15.0}
  ]
}
```

#### Step 2: Get High-Confidence Bot Mentions

```bash theme={null}
GET /workspaces/123/mentions?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&bot_ratings[]=likely&bot_ratings[]=very_likely&bot_ratings[]=almost_certain&limit=50&offset=0
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
[
  {
    "id": 12345,
    "title": "Example mention title",
    "text": "Example mention content...",
    "author": "@example_account",
    "botRating": "Almost Certain",
    "channels": ["twitter"],
    "enrichments": {
      "narratives": [
        {"id": 567, "confidence": 85}
      ]
    }
  }
]
```

#### Step 3: Analyze Bot Narratives

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=567&since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&bot_ratings[]=likely&bot_ratings[]=very_likely&bot_ratings[]=almost_certain
Authorization: Bearer {token}
```

### Analysis Tips

* High bot percentages (especially "Almost Certain" and "Very Likely") may indicate coordinated campaigns
* Compare bot-driven narratives with overall narratives to identify amplification patterns
* Track bot activity over time to detect bot network activation
* Cross-reference bot mentions with specific authors to identify bot accounts

***

## 3. Channel Distribution Analysis

### Overview

Understand channel mix and track how narratives spread from social platforms
to mainstream news. This workflow helps you identify cross-channel narrative
propagation and understand where conversations originate and amplify.

### Prerequisites

* A workspace with multiple channels enabled (news and social media)

### Step-by-Step Guide

1. **Get Overall Channel Distribution**
   See the current breakdown of mentions across all channels.

2. **Track Channel Volume Over Time**
   Use timeline analytics with channel grouping to see volume trends per channel.

3. **Identify Cross-Channel Spread**
   Analyze timeline data to identify when narratives jump from social to news.

4. **Track Specific Narrative Channel Progression**
   Optionally filter to a specific narrative to see its channel journey.

### Example Requests

#### Step 1: Get Channel Distribution

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=channels&since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "groupBy": "channels",
  "totalCount": 200000,
  "groups": [
    {"key": "twitter", "name": "X (Twitter)", "count": 80000, "percentage": 40.0},
    {"key": "news", "name": "News", "count": 60000, "percentage": 30.0},
    {"key": "reddit", "name": "Reddit", "count": 30000, "percentage": 15.0},
    {"key": "youtube", "name": "YouTube", "count": 20000, "percentage": 10.0},
    {"key": "facebook", "name": "Facebook", "count": 10000, "percentage": 5.0}
  ]
}
```

#### Step 2: Track Volume Over Time by Channel

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&group_by=channels
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
{
  "totalCount": 200000,
  "buckets": [
    {
      "date": "2025-01-15T00:00:00Z",
      "count": 5000,
      "groups": [
        {"key": "twitter", "count": 2500},
        {"key": "news", "count": 1500},
        {"key": "reddit", "count": 1000}
      ]
    },
    {
      "date": "2025-01-16T00:00:00Z",
      "count": 12000,
      "groups": [
        {"key": "twitter", "count": 4000},
        {"key": "news", "count": 6000},
        {"key": "reddit", "count": 2000}
      ]
    }
  ]
}
```

#### Step 3: Track Specific Narrative Across Channels

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&group_by=channels&narratives.id[]=567
Authorization: Bearer {token}
```

### Analysis Tips

* Look for days where news volume spikes after social media activity (indicating narrative spread)
* Compare channel percentages over time to see which channels are driving conversation
* Identify "tipping points" when narratives move from niche platforms to mainstream
* Use the groups array in timeline buckets to see daily channel breakdowns

***

## 4. Counter-Messaging Effectiveness

### Overview

Measure favorability changes before and after making a public statement to
assess the impact of your messaging. This workflow helps you quantify how
counter-messaging efforts affect brand perception.

### Prerequisites

* A workspace with a "Favorability" Smart Category configured
* Knowledge of when your public statement was made

### Step-by-Step Guide

1. **Get Pre-Statement Favorability**
   Query distribution for the period before your statement (e.g., 7 days prior).

2. **Get Post-Statement Favorability**
   Query distribution for the period after your statement (e.g., 7 days after).

3. **Compare Percentages**
   Calculate the difference in favorability classifications to measure impact.

### Example Requests

#### Step 1: Get Pre-Statement Distribution

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=smart_category_enrichment_id:244&since=2025-01-08T00:00:00Z&to=2025-01-14T23:59:59Z
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "groupBy": "smart_category_enrichment_id:244",
  "totalCount": 10000,
  "groups": [
    {"key": "c0", "name": "Favorable", "count": 3000, "percentage": 30.0},
    {"key": "c1", "name": "Unfavorable", "count": 2500, "percentage": 25.0},
    {"key": "c2", "name": "Neutral", "count": 3000, "percentage": 30.0},
    {"key": "c3", "name": "Not Applicable", "count": 1500, "percentage": 15.0}
  ]
}
```

#### Step 2: Get Post-Statement Distribution

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=smart_category_enrichment_id:244&since=2025-01-15T00:00:00Z&to=2025-01-21T23:59:59Z
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "groupBy": "smart_category_enrichment_id:244",
  "totalCount": 12000,
  "groups": [
    {"key": "c0", "name": "Favorable", "count": 4800, "percentage": 40.0},
    {"key": "c1", "name": "Unfavorable", "count": 2400, "percentage": 20.0},
    {"key": "c2", "name": "Neutral", "count": 3600, "percentage": 30.0},
    {"key": "c3", "name": "Not Applicable", "count": 1200, "percentage": 10.0}
  ]
}
```

### Analysis Tips

* Compare percentage changes: "Favorable" increased from 30% to 40% (+10 points)
* Monitor "Unfavorable" decreases to measure reputation recovery
* Track "Neutral" and "Not Applicable" to understand overall sentiment distribution
* Consider volume changes alongside percentage shifts (more mentions with
  better sentiment is ideal)
* Use longer time windows (14-30 days) for more stable comparisons

***

## 5. Velocity Tracking

### Overview

Track the rate at which discourse is increasing or decreasing for a specific
theme from a Smart Category. This workflow helps you identify accelerating or
decelerating conversations and detect emerging trends early.

### Prerequisites

* A workspace with Smart Categories configured for the theme you want to track

### Step-by-Step Guide

1. **Identify Smart Category Enrichment ID**
   Query filters to find the enrichment\_id for your theme's Smart Category.

2. **Get Timeline Filtered by Theme**
   Retrieve timeline analytics filtered to a specific Smart Category classification.

3. **Calculate Velocity**
   Analyze day-over-day volume changes to identify acceleration or deceleration.

4. **Identify Trend Changes**
   Look for inflection points where velocity shifts significantly.

### Example Requests

#### Step 1: Find Theme Smart Category

```bash theme={null}
GET /workspaces/123/available-filters
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
{
  "smart_categories": {
    "models": [
      {
        "name": "Product Adoption Trend",
        "enrichment_id": 294,
        "options": [
          {"name": "Increasing Adoption", "value": "294:c0"},
          {"name": "Decreasing Adoption", "value": "294:c1"},
          {"name": "No Indication", "value": "294:c2"}
        ]
      }
    ]
  }
}
```

#### Step 2: Get Timeline for Theme

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&smart_categories[]=294:c0
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "totalCount": 50000,
  "buckets": [
    {"date": "2025-01-01T00:00:00Z", "count": 500},
    {"date": "2025-01-02T00:00:00Z", "count": 550},
    {"date": "2025-01-03T00:00:00Z", "count": 600},
    {"date": "2025-01-04T00:00:00Z", "count": 750},
    {"date": "2025-01-05T00:00:00Z", "count": 1000},
    {"date": "2025-01-06T00:00:00Z", "count": 1200}
  ]
}
```

### Analysis Tips

* Calculate day-over-day growth rate:
  `(today - yesterday) / yesterday * 100`
* Look for consistent acceleration (increasing growth rates) indicating viral
  trends
* Identify deceleration points where growth slows, potentially signaling peak
  interest
* Compare velocity across different Smart Category classifications to see
  which themes are trending
* Use 7-day moving averages to smooth out daily volatility and identify true trends

***

## 6. Threat Monitoring

### Overview

Filter high-threat narratives and get analytics to identify and prioritize
narratives requiring immediate attention. This workflow helps security and
risk teams monitor and respond to emerging threats.

### Prerequisites

* A workspace with narrative threat scoring enabled

### Step-by-Step Guide

1. **Get High-Threat Narratives**
   Filter narratives by `threatLevel=high` and sort by `threatScore` descending.

2. **Analyze Threat Volume Over Time**
   Get timeline analytics for specific high-threat narratives to see volume trends.

3. **Identify Threat Sources**
   Get distribution by channels and authors for threat narratives to understand who's driving them.

4. **Get Threat Mentions**
   Retrieve actual mentions from high-threat narratives for detailed analysis.

### Example Requests

#### Step 1: Get High-Threat Narratives

```bash theme={null}
GET /workspaces/123/narratives?threatLevel=high&sort=relevancy&limit=50
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
[
  {
    "id": 789,
    "title": "Security breach discussion",
    "threatScore": 9,
    "aggregations": {
      "mentionCount": 5000,
      "avgSentiment": -75,
      "relevancyScore": 95
    }
  },
  {
    "id": 790,
    "title": "Coordinated attack planning",
    "threatScore": 8,
    "aggregations": {
      "mentionCount": 3000,
      "avgSentiment": -80,
      "relevancyScore": 90
    }
  }
]
```

#### Step 2: Get Timeline for High-Threat Narrative

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&narratives.id[]=789
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
{
  "totalCount": 5000,
  "buckets": [
    {"date": "2025-01-15T00:00:00Z", "count": 100},
    {"date": "2025-01-16T00:00:00Z", "count": 250},
    {"date": "2025-01-17T00:00:00Z", "count": 500}
  ]
}
```

#### Step 3: Get Channel Distribution for Threats

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=channels&since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&narratives.id[]=789
Authorization: Bearer {token}
```

#### Step 4: Get Threat Mentions

```bash theme={null}
GET /workspaces/123/mentions?narratives.id[]=789&sort=published&limit=50&offset=0
Authorization: Bearer {token}
```

### Analysis Tips

* Prioritize narratives with both high `threatScore` (8-10) and high
  `relevancyScore` (>80)
* Monitor volume acceleration in threat narratives as an early warning signal
* Identify which channels and authors are amplifying threats
* Track threatScore trends over time to see if threats are escalating
* Combine threat monitoring with bot detection to identify coordinated threat
  campaigns

***

## 7. Narrative Origin Assessment

### Overview

Understand when and how a narrative emerged by analyzing volume over time and
examining mentions from the narrative's early days. This workflow helps you
identify key messaging, actors, and channels that drove narrative emergence.

### Prerequisites

* A workspace with narratives enabled
* A specific narrative ID to analyze

### Step-by-Step Guide

1. **Get Narrative Volume Timeline**
   Retrieve timeline analytics filtered by the narrative ID to identify when it emerged.

2. **Identify Early Days**
   Find the date range when narrative volume started increasing significantly.

3. **Get Early Mentions**
   Retrieve mentions from those early days filtered by the narrative ID.

4. **Analyze Origin Characteristics**
   Examine authors, domains, channels, and content from early mentions.

5. **Sort Chronologically**
   Sort mentions by published date to see the narrative's chronological emergence.

### Example Requests

#### Step 1: Get Narrative Timeline

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&narratives.id[]=567
Authorization: Bearer {token}
```

**Response:**

```json theme={null}
{
  "totalCount": 25000,
  "buckets": [
    {"date": "2025-01-10T00:00:00Z", "count": 50},
    {"date": "2025-01-11T00:00:00Z", "count": 75},
    {"date": "2025-01-12T00:00:00Z", "count": 200},
    {"date": "2025-01-13T00:00:00Z", "count": 500},
    {"date": "2025-01-14T00:00:00Z", "count": 1200}
  ]
}
```

#### Step 2: Get Early Mentions

```bash theme={null}
GET /workspaces/123/mentions?since=2025-01-10T00:00:00Z&to=2025-01-13T23:59:59Z&narratives.id[]=567&sort=published&order=asc&limit=50&offset=0
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
[
  {
    "id": 1001,
    "title": "Early narrative mention",
    "text": "Content discussing the narrative theme...",
    "author": "@influencer_account",
    "domain": "twitter.com",
    "channels": ["twitter"],
    "published": "2025-01-10T08:30:00Z",
    "reach": 500000
  },
  {
    "id": 1002,
    "title": "Follow-up discussion",
    "text": "Expanding on the narrative...",
    "author": "Reporter Name",
    "domain": "news.example.com",
    "channels": ["news"],
    "published": "2025-01-11T14:20:00Z",
    "reach": 2000000
  }
]
```

#### Step 3: Get Author Distribution for Early Days

```bash theme={null}
GET /workspaces/123/analytics/distribution?group_by=authors&since=2025-01-10T00:00:00Z&to=2025-01-13T23:59:59Z&narratives.id[]=567
Authorization: Bearer {token}
```

### Analysis Tips

* Identify the "patient zero" mention - the first mention with high reach that
  likely sparked the narrative
* Look for cross-channel amplification: social media mentions followed by news
  coverage
* Analyze author reach to identify key amplifiers who drove narrative spread
* Compare early messaging with later messaging to see how the narrative
  evolved
* Track domain distribution to see which publishers picked up the narrative
  first
* Use chronological sorting to understand the narrative's progression path

***

## 8. Alerting on New Threatening Narratives

### Overview

Poll for newly emerged high-threat narratives and trigger alerts when threats
are detected. This workflow enables security and risk teams to build automated
alerting pipelines that surface new threatening narratives as they emerge.

### Prerequisites

* A workspace with narrative threat scoring enabled
* A scheduled job or cron that runs at your desired alert frequency (e.g., hourly, daily)

### Step-by-Step Guide

1. **Poll for High-Threat Narratives**
   Query narratives with `threatLevel=high` and a recent date range (`since`/`to`).

2. **Sort by Creation Date**
   Sort by `created` descending to surface the newest narratives first.

3. **Identify New Narratives**
   Compare returned narrative IDs against a stored set of previously seen IDs to
   detect truly new threats (not yet alerted on).

4. **Fetch Details for Alerts**
   For each new threat, optionally retrieve mentions or timeline data to include
   in the alert payload.

5. **Update Seen Narrative IDs**
   Persist the narrative IDs you've alerted on so subsequent runs don't re-alert.

### Example Requests

#### Step 1: Poll for Recent High-Threat Narratives

```bash theme={null}
GET /workspaces/123/narratives?threatLevel=high&since=2025-01-15T00:00:00Z&to=2025-01-15T23:59:59Z&sort=created&limit=50
Authorization: Bearer {token}
```

**Response snippet:**

```json theme={null}
[
  {
    "id": 791,
    "title": "Emerging threat discussion",
    "threatScore": 9,
    "aggregations": {
      "mentionCount": 150,
      "avgSentiment": -82,
      "relevancyScore": 92
    },
    "created": "2025-01-15T14:32:00Z"
  }
]
```

#### Step 2: Get Mentions for New Threat (Alert Payload)

```bash theme={null}
GET /workspaces/123/mentions?narratives.id[]=791&sort=published&limit=5&offset=0
Authorization: Bearer {token}
```

#### Step 3: Get Timeline for Context

```bash theme={null}
GET /workspaces/123/analytics/timeline?since=2025-01-15T00:00:00Z&to=2025-01-15T23:59:59Z&narratives.id[]=791
Authorization: Bearer {token}
```

### Analysis Tips

* Use a narrow `since`/`to` window (e.g., last hour) for frequent polling to catch
  new threats quickly
* Store narrative IDs in a database or cache to deduplicate alerts across runs
* Consider filtering by `threatScore` threshold (e.g., only alert when >= 8) by
  filtering the response client-side
* Include narrative title, threatScore, mentionCount, and sample mentions in
  alert notifications for context
* Integrate with Slack, PagerDuty, or email to deliver alerts to the right teams