Track sound growth

You will record how many reels use one Instagram sound, once a day, without running a scheduler of your own, and get a webhook when the count jumps.

Why track a sound's reel count?

The number of reels using a sound, read on the same sound day after day, is that sound's adoption curve. A sound going from 1,700 reels to 2,400 in a week is spreading; one sitting at 1,700 is not. One reading tells you the size, the series tells you the direction.

You could call GET /v1/instagram/audio/reels from a cron job and store data.total yourself. A Monitor does the same call on a schedule, keeps only the number, works out the change since the previous day, and alerts you when it crosses a threshold you set.

Step 1: find the sound id

The Monitor takes the sound's audio_id. Three ways to get one:

• From a reel you already have: GET /v1/instagram/post?url=... (1 credit) returns the sound id at data.post.ext.music_id when the reel uses licensed music. GET /v1/instagram/profile/reels?handle=... (1 credit a page) carries the same leaf on every reel that has one.
• From a link: the numeric id in an instagram.com/reels/audio/{audio_id}/ URL.
• By name: GET /v1/instagram/search/music?query=... (5 credits) searches Instagram's audio library and returns matching tracks with their ids.
• A whole cluster of uploads: Instagram groups different uploads of the same sound under one cluster id, which GET /v1/instagram/audio/reels returns on each reel at post.ext.audio_cluster_id (and GET /v1/instagram/profile/reels with include=stats). Pass that cluster id as the audio_id and total counts every upload in the cluster, so one trend is tracked as one number instead of several small ones.

curl "https://www.socialcrawl.dev/v1/instagram/post?url=https://www.instagram.com/p/DcCH2ZygIiP/" \
  -H "x-api-key: YOUR_API_KEY"

Looking for a sound worth tracking first? GET /v1/prism/trend-board?country_code=US (30 credits) returns rising_sounds for one country, next to breakout posts and rising hashtags.

Step 2: create the Monitor

Create a numbers-only Monitor: track keeps just total from each run, the reel count Instagram shows for the sound.

curl -X POST "https://www.socialcrawl.dev/v1/monitors" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sound 1581178662912126 daily",
    "recipe": "instagram/audio/reels",
    "params": { "audio_id": "1581178662912126" },
    "cadence": "daily",
    "track": { "metrics": ["total"] },
    "alert_rules": [{ "metric": "total", "op": "pct_change_gt", "value": 5 }],
    "webhook_url": "https://example.com/hooks/sound-growth",
    "suppress_webhook_unless_alert": true
  }'

{
  "monitor": {
    "id": "mon_7Qk2R9xLpV",
    "recipe": "instagram/audio/reels",
    "cadence": "daily",
    "status": "active",
    "alert_rules": [{ "metric": "total", "op": "pct_change_gt", "value": 5 }],
    "estimated_cost_per_run": 2,
    "estimated_monthly_cost": 60,
    "track": { "metrics": ["total"], "row_key": null, "max_rows": 100 },
    "warnings": []
  },
  "webhook_secret": "whsec_..."
}

The alert fires when total grows by more than 5% since the previous run. With suppress_webhook_unless_alert set, your endpoint hears from SocialCrawl only on those days. Leave out webhook_url and suppress_webhook_unless_alert for a download-only Monitor that you read in step 3.

The path is checked when you create the Monitor, for free. A typo such as totl returns 400 with Did you mean 'total'? and creates nothing, so a Monitor that exists is one that records a real number.

Step 3: read the series

GET /v1/monitors/{monitor_id}/timeseries returns every stored reading. It is free.

curl "https://www.socialcrawl.dev/v1/monitors/mon_7Qk2R9xLpV/timeseries?from=2026-09-01T00:00:00Z" \
  -H "x-api-key: YOUR_API_KEY"

{
  "metric_keys": ["total"],
  "points": [
    { "t": "2026-09-29T09:00:00.000Z", "metrics": { "total": 1698 } },
    { "t": "2026-09-30T09:00:00.000Z", "metrics": { "total": 1733 } }
  ],
  "series": [
    {
      "row_id": "_",
      "metric": "total",
      "points": [
        { "t": "2026-09-29T09:00:00.000Z", "value": 1698 },
        { "t": "2026-09-30T09:00:00.000Z", "value": 1733 }
      ]
    }
  ],
  "series_truncated": false
}

A number read off the page itself, like total, is stored under the row id _. For a spreadsheet, GET /v1/monitors/{monitor_id}/export?format=csv returns the same readings with the change since each previous run. See Monitor webhooks for the full reference.

The same thing on TikTok

GET /v1/tiktok/song (1 credit) returns the number of videos using a TikTok sound at data.post.engagement.views. On this endpoint that leaf is a video count, not a play count. Track it with the sound's clipId:

curl -X POST "https://www.socialcrawl.dev/v1/monitors" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "tiktok/song",
    "params": { "clipId": "7439295283975702544" },
    "cadence": "daily",
    "track": { "metrics": ["post.engagement.views"] },
    "alert_rules": [{ "metric": "post.engagement.views", "op": "pct_change_gt", "value": 5 }]
  }'

That is also 2 credits a day. To find a sound's clipId, GET /v1/tiktok/post?url=... (1 credit) returns the video's sound id at data.post.ext.music_id.

Things to know

• total comes from the first page only. Instagram shows the count on the first page of a sound's reels and later pages leave it null, so do not put a cursor in the Monitor's params. When Instagram does not show a count for a sound, that day's reading is stored as null, never a guess.
• One Monitor per sound. Each Monitor tracks one audio_id. The number you can keep active at once depends on your plan: Free 3, Starter 10, Growth 25, Pro 100, Enterprise 500.
• A failed run is refunded. If the call fails, the run's 2 credits come back and that day has no reading.
• Pause instead of deleting. PATCH /v1/monitors/{monitor_id} with {"status": "paused"} stops the runs and keeps the history.

Related