Reference
Social listening analytics
What the listening data can answer for our brand and against competitors, per-platform field coverage, and the build plan.
docs/LISTENING_ANALYTICS.md
What the social-listening data can answer, for our own brand and against competitors, and the
order it gets built in (F-104). Source data is SocialCrawl (third-party, logged-out public
pages — see the caveats) plus the official APIs measured in LISTENING_CAPABILITY.md.
Code: apps/api/src/modules/listening-tracking/, apps/api/src/modules/listening-explorer/.
Build plan
| Step | What | Status | Refs |
|---|---|---|---|
| — | Foundation: one-off keyword explorer across 10 platforms + SocialCrawl | ✅ 2026-09-30 | Performance → Social listening → Keyword explorer, F-104.1 |
| — | Foundation: saved terms + scheduled runs + stored mentions — hourly sweep on each term's cadence under a per-tick credit ceiling, every run and every mention kept | ✅ 2026-10-01 | F-104.2, D-053, D-054 |
| 1 | Data & mention explorer — search, platform / date / term filters, sorts, paging, mention detail with platform fields and raw payload, over stored rows only | ✅ 2026-10-05 | Performance → Social listening → Mentions, F-104.7, D-055 |
| 2 | Brand presence & engagement — headline numbers, platform split, mentions over time, top posts and creators, creator size, countries, languages, conversation type, paid vs organic, Reddit communities | ✅ 2026-10-05 | Performance → Social listening → Overview, F-104.3 |
| 3 | AI classification & conversation categories — intent, sentiment, complaint / question labels | 🔲 | F-104.5, F-104.6 |
| 4 | Trends, alerts & brand health | 🔲 | — |
| 5 | AI insights & competitive intelligence — share of voice, creator overlap, summaries | 🔲 | F-104.4 |
What SocialCrawl returns, per platform
Fill rate measured on a live 9-platform "Nike" run (2026-09-30), not taken from its docs. ✅ ≥ 75% of items · ⚠️ some · ❌ none.
| Platform | Text, author, time, link | Likes / comments | Views | Shares | Author followers | Est. reach | Intent & niche labels |
|---|---|---|---|---|---|---|---|
| TikTok | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (4%) |
| X | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| YouTube | ✅ | ❌ in search | ✅ | ❌ | ❌ | ✅ | ✅ |
| ✅ | ✅ upvotes | ❌ | ❌ | ❌ | ❌ | ✅ | |
| Threads | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ⚠️ |
| Bluesky | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
| Instagram (#hashtag) | ✅ | ✅ (likes 76%) | ⚠️ | ❌ | ❌ | ⚠️ | ❌ |
| ✅, no author | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | |
| ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
Analytics — our brand
| Analytic | Built from (listening_mentions) | Answers | Needs |
|---|---|---|---|
| Mention volume by platform | count by platform | Where the conversation about us lives | Step 1 data |
| New mentions per day | count by first_seen_at day | Is talk about us growing; spikes | Step 1 data over time |
| Impact-weighted mentions | views, likes, comments, shares, estimated_reach | Which mentions actually matter | Step 1 data |
| Top voices / creator discovery | author_*, author_followers, author_verified + engagement | Who talks about us with the biggest audience | Step 1 data |
| Buyer-intent queue | intent (e.g. asking_for_recommendation) | Posts where someone is about to buy | Step 1 data (strongest on Reddit, X, YouTube) |
| Sponsored vs organic | sponsored_p | How much buzz is paid; undisclosed sponsorship | Step 1 data |
| Themes and hashtags | text hashtags, niche, content_category | Which topics we are associated with | Step 1 data |
| Market / language mix | language | Which markets talk about us | Step 1 data |
| Format performance | raw duration, media + engagement | Which formats perform when people post about us | Step 1 data |
| Comment sentiment, complaints, questions | comment sources + labels | What people say under the biggest posts | Step 5 (extra credits or AI) |
Analytics — competitors
Same sources and cadence for every tracked term, so the brands are comparable.
| Analytic | Answers |
|---|---|
| Share of voice (mentions, engagement, views/reach per term) | Who owns the conversation, overall and per platform |
| Engagement quality (avg engagement per mention) | Do people care more when they talk about them |
| Platform footprint | Where they win, where we lead |
| Creator overlap | Creators on both brands; creators only on theirs (outreach targets) |
Their influencer activity (sponsored_p) | Which creators they pay, how much of their buzz is paid |
| Theme and hashtag gap | Topics tied to them and not to us |
| Intent comparison | Who gets more buyer-intent posts |
| Format benchmark | What formats perform in their conversation vs ours |
Caveats
| Caveat | Consequence |
|---|---|
| Each search returns 5–100 relevance-ranked posts — a sample, not a census | Compare terms only with identical sources and cadence; treat counts as indicators |
| Estimated reach and the intent / niche / sponsored labels are SocialCrawl's estimates | Label them as estimates in every UI |
| Field coverage differs by platform (table above) | Views/reach charts cover TikTok, X, YouTube only; Facebook has no author, Pinterest no engagement |
| SocialCrawl collects from logged-out public pages | Shipped to customers by product decision (D-056); the compliance review D-054 asked for is still open. Retention purge after LISTENING_RETENTION_DAYS |
| Billed per call | Per-tick ceiling LISTENING_MAX_CREDITS_PER_TICK and a per-organization monthly budget LISTENING_MONTHLY_CREDITS_PER_ORG (D-056); ~27 credits/day for 3 terms × 9 searches |