Example Workflows - PeakMetrics

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

Discover Smart Category Configuration Query the filters endpoint to find your Smart Category enrichment_id and available classifications.
Get Current Favorability Breakdown Use the distribution endpoint to see the current favorability mix across all classifications.
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 which themes 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
A Smart Category configured on the workspace (e.g. a “Favorability” model)

Step-by-Step Guide

Assess Overall Bot Presence Get distribution by bot ratings to see the overall bot landscape.
Identify High-Confidence Bots Filter to high-confidence bot ratings to focus on likely automated accounts.
Analyze Bot-Driven Mentions Retrieve mentions from high-confidence bots to understand their messaging.
Identify Bot-Driven Themes Group high-confidence bot mentions by a Smart Category to see which classifications bots are amplifying.

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"]
  }
]

Step 3: Analyze Bot-Driven Themes

GET /workspaces/123/analytics/distribution?group_by=smart_category_enrichment_id:244&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 Smart Category classifications with the overall workspace mix 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 conversations spread from social platforms to mainstream news. This workflow helps you identify cross-channel propagation and understand where conversations originate and amplify.

Prerequisites

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

Step-by-Step Guide

Get Overall Channel Distribution See the current breakdown of mentions across all channels.
Track Channel Volume Over Time Use timeline analytics with channel grouping to see volume trends per channel.
Identify Cross-Channel Spread Analyze timeline data to identify when conversations jump from social to news.
Track Channel Progression for a Specific Place Optionally filter to a country, state, or city to see that location’s 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 Channels for a Specific Place

Look up the location id with GET /locations and then scope the timeline to it. Here, locations.country[]=840 filters to the United States.

GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&group_by=channels&locations.country[]=840
Authorization: Bearer {token}

Analysis Tips

Look for days where news volume spikes after social media activity (indicating cross-channel spread)
Compare channel percentages over time to see which channels are driving conversation
Identify “tipping points” when a conversation moves 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

Get Pre-Statement Favorability Query distribution for the period before your statement (e.g., 7 days prior).
Get Post-Statement Favorability Query distribution for the period after your statement (e.g., 7 days after).
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

Identify Smart Category Enrichment ID Query filters to find the enrichment_id for your theme’s Smart Category.
Get Timeline Filtered by Theme Retrieve timeline analytics filtered to a specific Smart Category classification.
Calculate Velocity Analyze day-over-day volume changes to identify acceleration or deceleration.
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. Classification Surge Origin Assessment

Overview

Understand when and how a surge in a specific Smart Category classification emerged by analyzing volume over time and examining mentions from the surge’s early days. This workflow helps you identify key messaging, actors, and channels that drove the surge.

Prerequisites

A workspace with a Smart Category configured (e.g. a “Disinformation Analysis” model)
A specific {enrichment_id}:{category_key} to analyze (e.g. 244:c0)

Step-by-Step Guide

Get Classification Volume Timeline Retrieve timeline analytics filtered by the Smart Category classification to identify when the surge began.
Identify Early Days Find the date range when volume for that classification started increasing significantly.
Get Early Mentions Retrieve mentions from those early days filtered by the same classification.
Analyze Origin Characteristics Examine authors, domains, channels, and content from early mentions.
Sort Chronologically Sort mentions by published date to see the surge’s chronological emergence.

Example Requests

Step 1: Get Classification Timeline

GET /workspaces/123/analytics/timeline?since=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z&smart_categories[]=244:c0
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&smart_categories[]=244:c0&sort=published&order=asc&limit=50&offset=0
Authorization: Bearer {token}

Response snippet:

[
  {
    "id": 1001,
    "title": "Early mention",
    "text": "Content matching the classification...",
    "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 same theme...",
    "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&smart_categories[]=244:c0
Authorization: Bearer {token}

Analysis Tips

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

​1. Brand Sentiment Tracking

​Overview

​Prerequisites

​Step-by-Step Guide

​Example Requests

​Step 1: Find Smart Category Enrichment ID

​Step 2: Get Current Distribution

​Step 3: Track Favorability Over Time

​Analysis Tips

​2. Bot Detection Analysis

​Overview

​Prerequisites

​Step-by-Step Guide

​Example Requests

​Step 1: Get Bot Rating Distribution

​Step 2: Get High-Confidence Bot Mentions

​Step 3: Analyze Bot-Driven Themes

​Analysis Tips

​3. Channel Distribution Analysis

​Overview

​Prerequisites

​Step-by-Step Guide

​Example Requests

​Step 1: Get Channel Distribution

​Step 2: Track Volume Over Time by Channel

​Step 3: Track Channels for a Specific Place

​Analysis Tips

​4. Counter-Messaging Effectiveness

​Overview

​Prerequisites

​Step-by-Step Guide

​Example Requests

​Step 1: Get Pre-Statement Distribution

​Step 2: Get Post-Statement Distribution

​Analysis Tips

​5. Velocity Tracking

​Overview

​Prerequisites

​Step-by-Step Guide

​Example Requests

​Step 1: Find Theme Smart Category

​Step 2: Get Timeline for Theme

​Analysis Tips

​6. Classification Surge Origin Assessment

​Overview

​Prerequisites

​Step-by-Step Guide

​Example Requests

​Step 1: Get Classification Timeline

​Step 2: Get Early Mentions

​Step 3: Get Author Distribution for Early Days

​Analysis Tips

1. Brand Sentiment Tracking

Overview

Prerequisites

Step-by-Step Guide

Example Requests

Step 1: Find Smart Category Enrichment ID

Step 2: Get Current Distribution

Step 3: Track Favorability Over Time

Analysis Tips

2. Bot Detection Analysis

Overview

Prerequisites

Step-by-Step Guide

Example Requests

Step 1: Get Bot Rating Distribution

Step 2: Get High-Confidence Bot Mentions

Step 3: Analyze Bot-Driven Themes

Analysis Tips

3. Channel Distribution Analysis

Overview

Prerequisites

Step-by-Step Guide

Example Requests

Step 1: Get Channel Distribution

Step 2: Track Volume Over Time by Channel

Step 3: Track Channels for a Specific Place

Analysis Tips

4. Counter-Messaging Effectiveness

Overview

Prerequisites

Step-by-Step Guide

Example Requests

Step 1: Get Pre-Statement Distribution

Step 2: Get Post-Statement Distribution

Analysis Tips

5. Velocity Tracking

Overview

Prerequisites

Step-by-Step Guide

Example Requests

Step 1: Find Theme Smart Category

Step 2: Get Timeline for Theme

Analysis Tips

6. Classification Surge Origin Assessment

Overview

Prerequisites

Step-by-Step Guide

Example Requests

Step 1: Get Classification Timeline

Step 2: Get Early Mentions

Step 3: Get Author Distribution for Early Days

Analysis Tips