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

Response snippet:

Step 2: Get Current Distribution

Response:

Step 3: Track Favorability Over Time

Response snippet:

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

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

Response:

Step 2: Get High-Confidence Bot Mentions

Response snippet:

Step 3: Analyze Bot-Driven Themes

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

  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 conversations jump from social to news.
  4. 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

Response:

Step 2: Track Volume Over Time by Channel

Response snippet:

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.

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

  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

Response:

Step 2: Get Post-Statement Distribution

Response:

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

Response snippet:

Step 2: Get Timeline for Theme

Response:

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

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

Example Requests

Step 1: Get Classification Timeline

Response:

Step 2: Get Early Mentions

Response snippet:

Step 3: Get Author Distribution for Early Days

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

7. Topic Sizing with Explore

Overview

Gauge how big a conversation is, and where it is happening, before you create a workspace for it. This workflow uses Explore queries to test a search query against the media ecosystem and decide whether it is worth tracking.

Prerequisites

  • A search query for the topic you want to size
  • No workspace is required

Step-by-Step Guide

  1. Check Overall Volume Run the query through the Explore timeline endpoint to see how much conversation it matches and how volume has trended.
  2. Find Where the Conversation Happens Use the Explore distribution endpoint grouped by channel to see which channels carry the conversation.
  3. Identify Leading Sources Group by domain to see which sites publish the most matching content (up to the top 50 domains).
  4. Create a Workspace If the topic is worth tracking, create a workspace with the refined query and channels.

Example Requests

Step 1: Get Volume Over Time

Response snippet:

Step 2: Get Channel Distribution

Response snippet:

Step 3: Get Domain Distribution

Step 4: Create the Workspace

Analysis Tips

  • Refine the query and rerun Step 1 until the volume and trend look right before creating a workspace
  • Explore is limited to 5 queries per user per minute and 1,000 queries per user per endpoint per month, shared with the Explore tools in the PeakMetrics MCP server, so iterate deliberately. Every request counts toward the per-minute limit; only successful (200) requests count toward the monthly quota. A 429 with error: "quota_exceeded" means that endpoint’s monthly quota is used up until the start of the next calendar month (UTC); error: "rate_limited" means wait retryAfterSeconds and try again
  • reddit covers the Reddit posts and comments your account is entitled to
  • since can reach back 12 months (a since up to one day earlier is clamped to that limit), and a to in the future is clamped to today. Timeline buckets are UTC calendar days, one per day in the range, with 0 for days without matching mentions
  • Data for some channels may be estimated from a large-scale firehose sample, so treat counts as directional when comparing channels

8. Comparing Topics with Explore

Overview

Compare the share of voice of competing brands or topics across channels and languages without building a workspace for each one. This workflow runs the same Explore request for each topic and compares the results side by side.

Prerequisites

  • A search query for each brand or topic you want to compare

Step-by-Step Guide

  1. Run a Timeline per Topic Send one Explore timeline request per query, using the same channels and date range.
  2. Compare Volume Line up totalCount and bucket counts across topics to compare share of voice over time.
  3. Compare Language Reach Use the Explore distribution endpoint grouped by language to see how far each topic travels beyond English.

Example Requests

Step 1: Timeline for Each Topic

Repeat the request with the competitor’s query (for example, "United Airlines" AND delay), keeping channels, since, to, and group_by unchanged.

Step 2: Language Distribution

Response snippet:

Analysis Tips

  • Keep every request identical except for query so the comparison is fair
  • When channels includes twitter, language breakdowns contain only en and non_en; drop twitter to see the full breakdown up to the top 100 languages per channel
  • Use group_by: "channels" on the timeline to see whether one brand’s conversation is concentrated on a single channel