# Music trend detection (/docs/recipes/music-trend-detection)



Music trend detection [#music-trend-detection]

Build an A\&R / music-trend dashboard that detects songs gaining traction across TikTok, Instagram, and Spotify before they hit the mainstream charts.

How do you spot a song trending on TikTok before the charts? [#how-do-you-spot-a-song-trending-on-tiktok-before-the-charts]

Combine three signals: `GET /v1/tiktok/song/videos` counts how many videos use the sound, `GET /v1/instagram/audio/reels` shows whether the same audio is spreading on Reels, and `GET /v1/spotify/search` returns the canonical track stats. A log-weighted composite of the three catches breakouts while chart positions still lag — for 3 credits per song.

The problem [#the-problem]

By the time a song appears on a chart, the trend is priced in. The early signal is fragmented and it lives on the *creation* side before it shows up on the *consumption* side: TikTok creation velocity spikes first, Instagram Reels tells you whether the sound crossed platforms or stayed a single-app meme, and Spotify streams confirm the move afterwards. No single platform shows all three, and each exposes the data differently.

The solution [#the-solution]

Three standard-tier endpoints (1 credit each), one composite score:

* `GET /v1/tiktok/song/videos` — videos using a specific TikTok sound (param: `clipId`)
* `GET /v1/instagram/audio/reels` — reels using a specific Instagram audio track (param: `audio_id`)
* `GET /v1/spotify/search` — Spotify track / artist / podcast search (param: `query`)

The three platforms expose the same artefact (a track) from three different vantage points: TikTok shows who is making content with it, Instagram shows whether that creation behaviour crossed to a second short-video surface, and Spotify shows what listening actually did. A simple composite score fuses all three.

Resolving the two ids [#resolving-the-two-ids]

TikTok and Instagram key off ids, not track names, and both are stable per track — resolve once, then cache them:

* **TikTok `clipId`** — `GET /v1/tiktok/song` (1 credit) takes a `clipId` and returns the sound's metadata, so use it to confirm an id you already scraped from a `tiktok.com/music/...` URL.
* **Instagram `audio_id`** — the numeric id in an `instagram.com/reels/audio/{audio_id}/` URL. `GET /v1/instagram/search/music?query=espresso+sabrina+carpenter` (5 credits, advanced tier) searches Instagram's audio library by keyword and returns matching tracks with their ids.

Because both ids are stable, the 5-credit Instagram lookup is a one-off per track, not a per-run cost. The 3-credit figure below is the steady-state scan.

```typescript
// recipe-music-heat.ts
// Calculates a cross-platform "heat score" for one track.
// Run with: SOCIALCRAWL_KEY=sc_... npx tsx recipe-music-heat.ts

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

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

// Both ids are stable per track — resolve them once and store them.
const tiktokClipId = "7349589214432069122";
const instagramAudioId = "1392969992841787";
const spotifyQuery = "Espresso Sabrina Carpenter";

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, unknown>;
  };
}

const [tiktok, instagram, spotify] = await Promise.all([
  get("tiktok/song/videos", { clipId: tiktokClipId }),
  get("instagram/audio/reels", { audio_id: instagramAudioId }),
  get("spotify/search", { query: spotifyQuery }),
]);

type PostItem = { post?: { engagement?: { views?: number | null } } };

// TikTok reports a total usage count for the sound.
const tiktokVideos = (tiktok.data?.total as number | undefined) ?? 0;

// Instagram returns ONE PAGE of reels — there is no total. Summing views on
// the first page is a reach sample, not a catalogue count. Page with `cursor`
// if you want more depth; the weight below assumes one page.
const instagramReelViews = (
  (instagram.data?.items as PostItem[] | undefined) ?? []
).reduce((sum, item) => sum + (item.post?.engagement?.views ?? 0), 0);

const spotifyPlays =
  (spotify.data?.items as PostItem[] | undefined)?.[0]?.post?.engagement
    ?.views ?? 0;

// Weighted composite. Tune the weights for your use case.
const heat =
  Math.log10(tiktokVideos + 1) * 0.5 +
  Math.log10(instagramReelViews + 1) * 0.2 +
  Math.log10(spotifyPlays + 1) * 0.3;

console.log({
  tiktok_videos: tiktokVideos,
  instagram_reel_views: instagramReelViews,
  spotify_plays: spotifyPlays,
  heat_score: heat.toFixed(2),
});
```

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

```jsonc
// Aggregated, post-composite:
{
  "tiktok_videos": 2400000, // <-- `data.total` from TikTok song/videos
  "instagram_reel_views": 41800000, // <-- summed over ONE page of audio/reels
  "spotify_plays": 1180000000, // <-- top track from Spotify search
  "heat_score": "7.44", // <-- log-weighted composite of the three above
}
```

Credits cost [#credits-cost]

> **Cost per run:** 3 credits per song (3 platforms × 1 credit). All three endpoints are standard tier, so scanning a hundred tracks costs 300 credits. Add 5 credits once per track for the `/v1/instagram/search/music` id lookup if you don't already hold the `audio_id`.

Take it further [#take-it-further]

* See [Endpoint pricing](/docs/endpoint-pricing.md) for the full standard / advanced / premium tier breakdown.
* Swap `tiktokClipId` to discover any sound's reach, `instagramAudioId` for the matching Instagram audio, and `query` for any track + artist string.
* Want the discovery step too? `GET /v1/instagram/music/trending` (5 credits) and `GET /v1/instagram/reels/trending` (5 credits) surface what is already moving, which gives you candidate tracks to run this score against.
* Next: [Hybrid search-then-enrich](/docs/recipes/search-then-enrich.md) shows the most powerful composition — universal search feeding into per-platform deep-fetches.
* Platform references: [TikTok API](/platforms/tiktok), [Instagram API](/platforms/instagram), [Spotify API](/platforms/spotify). New here? [Quickstart](/docs/quickstart.md).