Skip to main content

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

GET /workspaces/123/available-filters
Authorization: Bearer {token}
Response snippet:
{
  "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

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

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

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

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:
[
  {
    "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

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

GET /workspaces/123/analytics/distribution?group_by=channels&since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z
Authorization: Bearer {token}
Response:
{
  "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

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

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

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

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

GET /workspaces/123/available-filters
Authorization: Bearer {token}
Response snippet:
{
  "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

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

GET /workspaces/123/narratives?threatLevel=high&sort=relevancy&limit=50
Authorization: Bearer {token}
Response snippet:
[
  {
    "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

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

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

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

GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&narratives.id[]=567
Authorization: Bearer {token}
Response:
{
  "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

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:
[
  {
    "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

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

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:
[
  {
    "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)

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

Step 3: Get Timeline for Context

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