# Track sound growth (/docs/recipes/track-sound-growth)

Record how many reels use an Instagram sound every day with one Monitor, and get an alert when it grows. 2 credits a day, no cron job to run.

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.

  **Cost per run:** 2 credits a day per sound. `GET /v1/instagram/audio/reels`
  costs 1 credit and a Monitor adds 1 credit per run, so a daily Monitor
  estimates at 60 credits a month. Creating the Monitor and reading its numbers
  are free.

## 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.

```bash title="cURL"
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.

```bash title="cURL"
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
  }'
```

```json title="Response"
{
  "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.

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

```json title="Response"
{
  "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](/docs/webhooks.md#numbers-only-monitors) 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`:

```bash title="cURL"
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

- [Monitor webhooks](/docs/webhooks.md): Every Monitor field, the rows format, export and signature checks.
- [Music trend detection](/docs/recipes/music-trend-detection.md): Score one song across TikTok, Instagram and Spotify in a single run.
- [Endpoint pricing](/docs/endpoint-pricing.md): Every endpoint and its credit cost.