# TikTok analytics dashboard (/docs/recipes/tiktok-analytics-dashboard)

Build a TikTok analytics dashboard from three endpoints (profile, videos, and comments) with engagement_rate included when the endpoint supports it and the required inputs are present. 3 credits per refresh.

You will build the data layer for a TikTok analytics dashboard over accounts you do not own: account KPIs at the top, a per-video performance table in the middle, and the current public comment feed of the top video at the bottom.

  **Cost per run:** 3 credits per dashboard refresh (profile + videos + one
  comment fetch, 1 credit each). Refreshing 50 accounts daily is 4,500 credits
  per month.

## How do you get TikTok analytics data from an API?

Three standard-tier calls cover a full dashboard refresh. `GET /v1/tiktok/profile` returns follower count plus pre-computed `engagement_rate` and `estimated_reach`, `GET /v1/tiktok/profile/videos` returns recent videos with views, likes, comments, and shares, and `GET /v1/tiktok/post/comments` returns the comment feed for any video URL.

TikTok's own analytics only cover accounts you own, and the Research API is gated to academics. Public-data endpoints plus consistent engagement math are what make a creator tool, an agency report, or a brand dashboard chartable over time.

## What you need

Three standard-tier endpoints (1 credit each):

| Endpoint                        | What it returns                                                              | Params                                                               |
| ------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `GET /v1/tiktok/profile`        | Profile stats with `computed.engagement_rate` and `computed.estimated_reach` | `handle` or `user_id`                                                |
| `GET /v1/tiktok/profile/videos` | Recent videos with views, likes, comments, and shares                        | `handle`; optional `sort_by=latest\|popular`, page with `max_cursor` |
| `GET /v1/tiktok/post/comments`  | The comment feed for one video                                               | `url`; page with `cursor`                                            |

Repeated comment requests may use the 5-minute endpoint cache. Cache hits cost 0 credits, and a `Cache-Control: no-cache` request forces a billed refresh.

Need audience geography (top follower countries and each country's share)? `GET /v1/tiktok/user/audience` is available at the advanced tier (5 credits). Age and gender are not publicly available on TikTok, so no endpoint returns them.

## The code

```typescript title="TypeScript"
// recipe-tiktok-dashboard.ts
// One full dashboard refresh for a TikTok account you don't own.
// Run with: SOCIALCRAWL_KEY=sc_... npx tsx recipe-tiktok-dashboard.ts

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

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

async function get(path: string, params: Record<string, string>) {
  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 {
    success: boolean;
    data?: Record<string, any>;
    error?: { message: string };
  };
}

// ── Panel 1: Account KPIs ──────────────────────────────────────────────────
const profile = await get("tiktok/profile", { handle });
if (!profile.success) throw new Error(profile.error?.message);

const kpis = {
  followers: profile.data!.author.followers,
  engagement_rate: profile.data!.computed.engagement_rate, // optional [0, 1] canonical metric
  estimated_reach: profile.data!.computed.estimated_reach,
};
console.log("account KPIs:", kpis);

// ── Panel 2: Per-video performance table ──────────────────────────────────
const videos = await get("tiktok/profile/videos", {
  handle,
  sort_by: "latest",
});

const rows = (videos.data?.items ?? []).map(
  (item: {
    post: {
      url: string;
      text: string | null;
      created_at: string | null;
      engagement: {
        views: number | null;
        likes: number | null;
        comments: number | null;
        shares: number | null;
      };
    };
  }) => ({
    caption: item.post.text?.slice(0, 40) ?? "",
    views: item.post.engagement.views,
    likes: item.post.engagement.likes,
    comments: item.post.engagement.comments,
    shares: item.post.engagement.shares,
    url: item.post.url,
  }),
);
console.table(rows.slice(0, 10));

// ── Panel 3: Comment feed of the current top video ─────────────────────────
const top = [...rows].sort((a, b) => (b.views ?? 0) - (a.views ?? 0))[0];
if (top) {
  const comments = await get("tiktok/post/comments", { url: top.url });
  for (const c of (comments.data?.items ?? []).slice(0, 5)) {
    console.log(`💬 ${c.comment?.text ?? c.text}`);
  }
}
```

## What you get back

```jsonc title="JSON"
// Panel 1, profile with computed fields:
{
  "account KPIs": {
    "followers": 155300000,
    "engagement_rate": 0.0731, // <-- pre-computed, clamped to [0, 1]
    "estimated_reach": 11352430, // <-- pre-computed
  },
}

// Panel 2, console.table of the latest videos:
// ┌─────────┬──────────────────────────┬──────────┬─────────┬──────────┬────────┐
// │ (index) │         caption          │  views   │  likes  │ comments │ shares │
// ├─────────┼──────────────────────────┼──────────┼─────────┼──────────┼────────┤
// │    0    │ "new dance w/ @..."      │ 12400000 │ 2100000 │  18400   │ 41000  │
// │    1    │ "grwm for the show"      │  8100000 │ 1400000 │  12100   │ 22000  │
// └─────────┴──────────────────────────┴──────────┴─────────┴──────────┴────────┘
```

## What to change

- **`handle`**: any public TikTok account. Schedule the script against a list of handles and write each refresh to a table keyed by `(handle, date)`, and time-series charts of followers and engagement rate fall out for free.
- **`sort_by`**: `latest` for cadence tracking, `popular` for a best-performers panel.
- **Go past the first page**: pass `max_cursor` on videos and `cursor` on comments. See [Pagination](/docs/pagination.md).
- **Add demographics**: one extra `GET /v1/tiktok/user/audience` call adds 5 credits per account.

## Related

- [Creator engagement scoring](/docs/recipes/creator-engagement-scoring.md): Compare this account against its Instagram and YouTube.
- [Competitor tracking](/docs/recipes/competitor-tracking.md): Run the same loop across a competitive set on four platforms.
- [Computed fields](/docs/computed-fields.md): The exact engagement_rate formula and the [0, 1] clamping rules.
- [TikTok API](/platforms/tiktok): Search, hashtags, trending, transcripts, followers, and the rest.
- [Quickstart](/docs/quickstart.md): New here? Get a key and make your first request.