Skip to Content
InsightsInsights — Overview

Insights — Overview

The Insights feature analyses historical data from connected channels to surface actionable recommendations for each client tenant. When a channel is connected and has historical data, a dedicated LLM agent fetches the last N months of metrics via the existing provider APIs, reasons over the data, and produces a structured insight report: strengths, weaknesses, opportunities, and recommendations — plus a markdown narrative summary.

Insights run per connected channel, with one dedicated agent per channel type. They can be triggered manually by the tenant or refreshed automatically on a weekly schedule.

Why This Is Needed

Channels currently display raw metrics in the dashboard but offer no interpretation. A client looking at their Google Search Console data sees numbers — not guidance. Insights turn those numbers into direction: “Your top 3 keywords are approaching page 1, but your CTR on branded terms has dropped 12% — here’s what to do.”

Supported Channels (v1)

Channel TypeProvider PackageData Fetched
Google Search Console@leadmetrics/provider-googleImpressions, clicks, CTR, avg position by query & page
Google Analytics@leadmetrics/provider-googleSessions, bounce rate, traffic sources, top pages, organic trends
Google Ads@leadmetrics/provider-googleCampaign performance, keyword metrics, cost/click, conversion rates
Meta Ads@leadmetrics/provider-metaCampaign impressions, reach, ROAS, spend vs results
Facebook Page@leadmetrics/provider-metaPage impressions, reach, engagement, post performance
Instagram@leadmetrics/provider-metaFeed reach, engagement rate, post performance trends
LinkedIn@leadmetrics/provider-linkedinPage stats, follower growth, share statistics, engagement
Google Business Profile@leadmetrics/provider-googleViews, searches, direction requests, call clicks

Live (May 2026): Website and Landing Page insights are now live — see sections below. Out of scope: WordPress, ZohoBooks, Bing Webmaster Tools — no historical metrics API.

Website Insights [Live May 2026]

Auto-triggered after every website crawl completes (and available on-demand). Stores a WebsiteInsight record (separate from ChannelInsight) with formula-based scores — SEO (title/meta/H1 coverage), Content (word count, depth), Technical (error rate, page count) — plus a Claude narrative using the 4-section format. See docs/channels/website/index.md for the full spec.

  • Queue: agent__website-insights
  • Worker: packages/agents/src/workers/insights/website-insights.worker.ts
  • API: /tenant/v1/website-insights (generate, list by channel, get by id, delete)
  • UI: Insights tab on Website channel detail; ScoreRings (Overall/SEO/Content/Technical) + history selector

Landing Page Insights [Live May 2026]

Auto-triggered when a landing page reaches client_approved status (and available on-demand). Scores are stored inline on the LandingPage model: seoScore, conversionScore, brandScore (0-100). Claude analyses the page content and returns both scores and the 4-section narrative.

  • Queue: agent__landing-page-scorer
  • Worker: packages/agents/src/workers/insights/landing-page-scorer.worker.ts
  • API: POST /tenant/v1/landing-pages/:id/generate-insights (dashboard), POST /dm/v1/landing-pages/:id/generate-insights (DM)
  • UI: Insights tab on landing page detail in both dashboard and DM portal

How It Works

Trigger (manual button, first channel connect, or weekly cron)
  ↓
API creates ChannelInsight record { status: "pending" }
  ↓
Enqueues job → agent__<channel-type>-insights queue
  ↓
Worker decrypts token from ConnectedChannel.tokenInfo
  ↓
Worker calls provider API → fetches metrics for the requested period
  ↓
Worker passes structured metrics + client context to Claude
  ↓
Claude returns { sections: { strengths[], weaknesses[], opportunities[], recommendations[] }, summary }
  ↓
Worker writes output to ChannelInsight { status: "done", insights: Json, summary: Text }
  ↓
WebSocket event emitted → dashboard updates in real time

Key Design Decisions

DecisionChoiceRationale
Raw data storageNot stored — fetch on-demand, store only insight outputAvoids schema bloat; data stays fresh from provider on each run
Output structureStructured JSON sections + markdown narrative summaryJSON powers UI cards; markdown renders in detail view
Trigger mechanismManual + on first channel connect + weekly scheduled auto-refreshOn-demand regeneration, zero-friction first insight, and automated freshness
Duplicate-run preventiontriggerInsightGeneration() checks for an in-flight (pending|generating) insight before creating a new record — returns existing ID if one is foundPrevents multiple concurrent runs when “Refresh” is clicked quickly or the period selector is used while a job is running
Accepted learningsHuman accepts individual insight items → ingested into channel_insights RAG datasetVerified observations persist and are available to all agents in future runs
Agent scopeOne agent per channel typeEach channel has different metrics, API calls, and prompt logic
Default periodLast 6 months (configurable: 3 or 12 months)Sufficient trend signal without bloating LLM context
UI placementNew /insights sidebar section + tab on each channel detail pageGlobal overview + contextual per-channel view

Accepted Learnings

When insights are generated, humans in the loop (DM reviewer or tenant admin) can accept individual insight items and optionally add a comment. Accepted items are ingested into the tenant’s channel_insights RAG dataset and become available to all agents as verified institutional knowledge about the client’s marketing performance.

This creates a cumulative improvement loop: each new insight run pre-loads prior accepted observations, builds on them rather than repeating them, and tracks whether identified opportunities have improved over time.

See Accepted Learnings for the full spec.

Insights — Implementation PlanInsights — UI Screens

© 2026 Leadmetrics — Internal use only