Your performance (own videos and ads)

viral-scout's main pipeline reads other creators' public numbers: views, likes, comments. The numbers that explain why a video works or an ad pays (hook rate, watch time, retention curve, completion, shares and saves, CTR, CVR, CPA, CAC, ROAS) are private to the account that posted it. They can only be measured for your own videos and ads.

The own-performance module brings them in, legitimately: official APIs on your own accounts, or the exports you download yourself. Then it computes one KPI framework (sections A–E), compares every video with your own medians, names the biggest problem per video, runs the 5 tests and watches for creative fatigue.

python -m viral_scout perf <profile>                     # pull every configured source → report
python -m viral_scout perf <profile> --no-pull           # rebuild from stored data (no API calls)
python -m viral_scout perf import <profile> <file.csv> --source meta|tiktok|youtube|generic
python -m viral_scout perf auth youtube                  # one-time OAuth for YouTube Analytics

Output:

• <output_dir>/<date>-performance.md: the report (sources, unit economics, KPIs A–E, priorities, per-video tables, the 5 tests, retention curves, diagnostics, fatigue, caveats, skipped sources).
• data/<profile>-perf-latest.json: everything, for the dashboard, the MCP tools and other agents.
• data/<profile>.sqlite, tables perf_records (latest record per video/ad) and perf_snapshots (one row per video per run when its numbers change), for trends and fatigue.
• Dashboard: /p/<profile>/performance (Your performance).
• MCP: perf_run (start a job, poll get_job), perf_results, perf_diagnose.

Every source is optional. A missing key puts that source under Skipped sources; the run never fails over it.

Sources

Out of scope: Shopify, Stripe or your landing-page analytics. Revenue comes from what the ad platforms attribute (or CSV columns you add). Real MER needs your total revenue: put it in economics.total_revenue.

Usage is counted per run (ig_insights_requests, youtube_analytics_requests, meta_ads_requests, tiktok_ads_requests, youtube_api_units) and stored in the JSON.

YouTube OAuth setup (once)

1. Google Cloud console → pick or create a project → APIs & Services → Library: enable YouTube Analytics API and YouTube Data API v3.
2. OAuth consent screen: External, add yourself as a test user (or publish it). Scopes are requested by the tool: yt-analytics.readonly and youtube.readonly.
3. Credentials → Create credentials → OAuth client ID → Desktop app. Copy the client ID and secret.
4. Save them (the secret goes through stdin):

   python -m viral_scout keys set YT_OAUTH_CLIENT_ID <client id>
   python -m viral_scout keys set YT_OAUTH_CLIENT_SECRET -
   

5. python -m viral_scout perf auth youtube. It prints Google's consent URL and opens it; sign in with the account that owns the channel. Google redirects to http://127.0.0.1:<port> where the tool is listening, and the refresh token is written to .env as YT_OAUTH_REFRESH_TOKEN. Use --no-browser to open the URL yourself, --port N for a fixed port.
6. Check it: python -m viral_scout keys test YT_OAUTH_REFRESH_TOKEN.

This is Google's installed-app flow with a loopback redirect and PKCE. The old copy-paste ("out-of-band") flow is no longer supported by Google. With the consent screen in "Testing", Google expires refresh tokens after 7 days; publish the app (it only reads your own data) to keep the token.

Meta and TikTok tokens

• Meta: Meta for Developers → create an app (Business type) with the Marketing API product → Business Settings → System users → add a system user, assign your ad account with "View performance", generate a token with ads_read. META_AD_ACCOUNT_ID is act_… or just the number from Ads Manager.
• TikTok: TikTok for Business developers → create an app with the Reporting scope → authorize it on your advertiser account → exchange the auth code for a long-term access token. TIKTOK_ADVERTISER_ID is in Ads Manager's account info.
• Instagram insights: the existing Graph API token, with instagram_manage_insights added (and instagram_manage_comments for comment sentiment).

All keys appear on the dashboard's Setup page with a live test.

CSV column mappings

Headers are matched case-insensitively, after removing a trailing currency code like (USD) or (EUR). Unknown columns are ignored and listed. Total rows are skipped. Exports broken down by day (Day, By Day, Date) are summed into one record per ad, and the daily rows feed the fatigue check. The table lives in code at viral_scout/perf/csvimport.py (COLUMNS).

Meta Ads Manager (--source meta, kind paid)

TikTok Ads Manager (--source tiktok, kind paid)

YouTube Studio (Advanced mode → Export → Table data, --source youtube, kind organic)

Generic (--source generic): any field name from viral_scout/perf/schema.py (impressions, views_3s, spend, purchases, revenue, duration, kind, platform, …) plus common aliases (cost, plays, orders, conversion value, saved, skip rate). Rows with spend are paid unless kind says otherwise.

KPIs

All rates are percentages. Every value in the JSON carries its numerator, denominator and the denominator actually used (denominator), because some KPIs fall back to a second-best denominator. Account totals are Σ numerators ÷ Σ denominators over the records that have both, so a TikTok ad without 3-second views doesn't dilute the hook rate.

A. Attention

B. Retention

C. Engagement

D. Traffic

E. Conversion and profit

Max affordable CAC from unit economics

Example: AOV 100, margin 40%, LTV 400, 20% of leads buy → max first-order CPA 40, break-even ROAS 2.5×, lifetime CAC limit 160, target CAC 53, max CPL 32.

Platform definitions differ

Never compare hook rates across platforms. Compare a TikTok ad with TikTok ads, a Meta ad with Meta ads. The tool does this: medians are per platform when there are at least 3 videos on it, else per kind.

Diagnostics

Benchmarks are your account's medians: same kind (organic or paid), same platform when it has 3+ records, and for retention KPIs the same length band (<15 s, 15–30 s, 30–60 s, 60 s+) when the band has 3+ videos. "Low" = under 75% of the benchmark; for costs, "high" = over 133%. A median over fewer than 3 videos isn't used.

The biggest problem is the finding with the highest weight × severity. Weights follow the priorities below, so a paid sales ad with a weak hook but a fine CPA isn't flagged first for its hook. Every diagnosis also lists caveats: attribution, "4× ROAS isn't profit" with your break-even ROAS, like-for-like length, hook proxies, small samples (<1,000 impressions or views).

The 5 tests

Per video, against your medians: ✅ at or above, ⚠️ within 25% below, ❌ more than 25% below (for costs the other way round), · not measurable.

Organic vs paid priorities

Set the goal in the profile (perf.goal: sales | leads | awareness). Without it: leads when the economics block has a lead-to-customer rate and no AOV, else sales.

Testing process

1. One goal per test. Decide the one number that decides the winner (hook rate for an opening test, CPA for an offer test) before you launch.
2. Variations of one variable. Same body, three hooks. Or same video, two offers. Change two things and you won't know which one worked.
3. Fair comparisons. Same audience, budget, placement and dates; similar lengths for retention; same platform for hook rates.
4. Early vs final signals. Hook rate and CTR settle after about 1,000 impressions per variation. CVR and CPA need volume: aim for ~50 conversions per variation before calling it, or use a cheaper proxy (landing page views, add to cart) and confirm later.
5. Watch fatigue. A winner decays: frequency climbs, CTR falls, CPA rises. The report flags it; refresh the hook first.
6. Scale validated winners. Raise budget gradually (about 20–30% every few days), keep the loser paused rather than deleted, and keep the winner as the control for the next test.

What marketers forget

• The offer. A better video won't save a weak offer. If CTR is high and CVR is low, test the offer before the creative.
• The landing page. Message match, mobile speed, one clear action. LPV rate under ~70% of link clicks usually means a slow page or accidental clicks.
• Profitability. ROAS is revenue, not profit. Know your break-even ROAS (1 ÷ gross margin) and your max CPA before you look at the dashboard.
• Attribution. Platforms claim conversions within their windows, including view-through. Add up what every platform claims and compare with your real orders. MER (total revenue ÷ total marketing spend) is the honest top-line number.
• Audience quality. Cheap clicks from the wrong people inflate CTR and kill CVR. Check placements, geography and lead quality, not only volume.

Profile blocks

economics:                    # your unit economics (all optional)
  avg_order_value: 120
  gross_margin: 0.6           # 0–1
  ltv: 480                    # revenue per customer over their lifetime
  lead_to_customer_rate: 0.2  # for lead-gen
  target_cpa: 40
  payback_months: 3
  monthly_revenue_per_customer: 60    # optional, for the payback CAC limit
  total_revenue: 25000        # optional, for real MER over the same period
  total_marketing_spend: 6000
perf:
  goal: sales                 # sales | leads | awareness
  days: 28                    # API lookback
  sources: [instagram, youtube, meta_ads, tiktok_ads]   # default: all with keys
  instagram: {limit: 30, comments: true, comment_posts: 10}
  youtube: {limit: 50, retention_videos: 10, comments: true, comment_posts: 10}

Verified API references (November 2026)

See references for the doc pages each source was built from.