# Creator engagement scoring (/docs/recipes/creator-engagement-scoring)



Creator engagement scoring [#creator-engagement-scoring]

Build a creator-vetting tool for an influencer-marketing team that needs to compare a creator's TikTok performance against their Instagram and YouTube on a single ranked dashboard.

How do you compare engagement rates across platforms? [#how-do-you-compare-engagement-rates-across-platforms]

Fetch the creator's profile from each platform's profile endpoint — `/v1/tiktok/profile`, `/v1/instagram/profile`, `/v1/youtube/channel` — and inspect `computed.engagement_rate`. When an endpoint supports `engagement_rate` and the required source inputs are present, SocialCrawl applies the canonical formula and clamps the result into `[0, 1]`, so populated values are directly comparable across platforms.

The problem [#the-problem]

Raw engagement numbers don't compare across platforms. A TikTok like is not an Instagram like is not a YouTube comment; follower counts inflate differently; and every analytics vendor defines "engagement rate" its own way. Vetting a creator means re-deriving the metric per platform — or trusting three incompatible dashboards.

The solution [#the-solution]

Three standard-tier profile endpoints (1 credit each), each carrying the same computed field:

* `GET /v1/tiktok/profile` — TikTok profile with `computed.engagement_rate`
* `GET /v1/instagram/profile` — Instagram profile with `computed.engagement_rate`
* `GET /v1/youtube/channel` — YouTube channel with `computed.engagement_rate`

This recipe shows the payoff for SocialCrawl's canonical schema. When an endpoint supports `engagement_rate` and the required source inputs are present, the value uses the same formula and is clamped into `[0, 1]`; a populated TikTok value of 0.082 is therefore directly comparable to a populated Instagram value of 0.082.

```typescript
// recipe-engagement-table.ts
// Compares one creator's engagement across TikTok, Instagram, and YouTube.
// Run with: SOCIALCRAWL_KEY=sc_... npx tsx recipe-engagement-table.ts

const KEY = process.env.SOCIALCRAWL_KEY;
if (!KEY) throw new Error("Set SOCIALCRAWL_KEY");

const BASE = "https://www.socialcrawl.dev/v1";
const handle = "mrbeast";

type Profile = {
  success: boolean;
  platform: string;
  data?: {
    author: { username: string | null; followers: number | null };
    computed: {
      engagement_rate: number | null;
      estimated_reach: number | null;
      language: string | null;
      content_category: string | null;
    };
  };
};

async function get(
  path: string,
  params: Record<string, string>,
): Promise<Profile> {
  const url = new URL(`${BASE}/${path}`);
  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
  const res = await fetch(url, { headers: { "x-api-key": KEY! } });
  return (await res.json()) as Profile;
}

const [tiktok, instagram, youtube] = await Promise.all([
  get("tiktok/profile", { handle }),
  get("instagram/profile", { handle }),
  get("youtube/channel", { handle }),
]);

const rows = [tiktok, instagram, youtube]
  .filter((p) => p.success && p.data)
  .map((p) => ({
    platform: p.platform,
    followers: p.data!.author.followers,
    engagement_rate: p.data!.computed.engagement_rate,
    estimated_reach: p.data!.computed.estimated_reach,
  }))
  .sort((a, b) => (b.engagement_rate ?? 0) - (a.engagement_rate ?? 0));

console.table(rows);
```

What you get back [#what-you-get-back]

```jsonc
// console.table output:
// ┌─────────┬───────────┬───────────┬─────────────────┬──────────────────┐
// │ (index) │ platform  │ followers │ engagement_rate │ estimated_reach  │
// ├─────────┼───────────┼───────────┼─────────────────┼──────────────────┤
// │    0    │ "tiktok"  │ 95000000  │       1         │     9500000      │ // <-- clamped, see warnings
// │    1    │ "youtube" │ 351000000 │     0.0842      │     2957420      │
// │    2    │ "instagram"│ 64200000 │     0.0413      │      265146      │
// └─────────┴───────────┴───────────┴─────────────────┴──────────────────┘
```

Credits cost [#credits-cost]

> **Cost per run:** 3 credits per creator (3 platforms × 1 credit). Vetting a 100-creator shortlist costs 300 credits.

Take it further [#take-it-further]

* See [Computed fields](/docs/computed-fields.md) for the per-platform engagement formulas and what triggers the `[0, 1]` clamp warning visible on TikTok above.
* Swap `mrbeast` for any handle on those three platforms — `charlidamelio`, `khaby.lame`, `mkbhd`.
* Next: [Music trend detection](/docs/recipes/music-trend-detection.md) applies the same parallel-fetch + composite-score pattern to music.
* Going deeper on one platform? See [TikTok analytics dashboard](/docs/recipes/tiktok-analytics-dashboard.md). Platform references: [TikTok API](/platforms/tiktok), [Instagram API](/platforms/instagram), [YouTube API](/platforms/youtube).