# Instagram Reel Trend Decay Radar (`chezsan770/instagram-reel-trend-decay-radar`) Actor

Track Instagram Reel momentum across scheduled snapshots. Detect breakouts, peaks, decay half-life, revivals, and forecast 24/72-hour views with evidence-backed confidence scores and action windows.

- **URL**: https://apify.com/chezsan770/instagram-reel-trend-decay-radar.md
- **Developed by:** [Sarthak Kumar](https://apify.com/chezsan770) (community)
- **Categories:** Social media, Videos, Automation
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## PulseDecay — Instagram Reel Trend Decay Radar

PulseDecay turns repeated Instagram Reel metric snapshots into decision-ready trend intelligence. It identifies whether a Reel is accelerating, breaking out, peaking, decaying, evergreen, reviving, or stalled—and shows whether there is still time to act.

Most Instagram APIs return cumulative counters. PulseDecay builds the missing time dimension:

- Cross-run metric history stored in a named Apify key-value store
- Interval views/hour, engagement velocity, and acceleration
- Observed peak velocity and percentage of peak
- Exponential decay half-life with model-fit quality
- 24-hour and 72-hour view forecasts with uncertainty ranges
- Breakout, acceleration, peak, decay, revival, and data-quality alerts
- Confidence scores that explain missing or weak evidence
- Within-run opportunity ranking and momentum percentiles
- Creator-normalized views-per-follower and engagement metrics
- Evidence series behind every conclusion

### Why it stands out

PulseDecay does not label a Reel “viral” because it has many views. It measures the direction and rate of change. A 20,000-view Reel gaining 5,000 views/hour can outrank a two-million-view Reel gaining almost nothing.

It also separates inference from evidence. Every record includes the normalized velocity series, observation duration, snapshot count, model fit, confidence reasons, and forecast range. Downstream systems can decide how much trust to place in each signal.

### Two collection modes

#### Live scrape orchestration

Scrape mode calls a configurable Instagram extraction Actor and normalizes common field names. By default it uses `apify/instagram-scraper`; `extractorActorId` and `extractorInput` can be replaced without changing the analytics layer. The Actor's no-input default runs a small built-in snapshot demo so Apify Store health checks remain deterministic and free of external scraping costs.

```json
{
  "mode": "scrape",
  "reelUrls": [
    "https://www.instagram.com/reel/REEL_CODE/"
  ],
  "profileUrls": [
    "https://www.instagram.com/example/"
  ],
  "maxReelsPerProfile": 30,
  "historyStoreName": "beauty-reels-radar",
  "alertSensitivity": "balanced"
}
```

The default extraction payload is:

```json
{
  "directUrls": ["..."],
  "resultsType": "reels",
  "resultsLimit": 30
}
```

If the chosen extractor uses different input names, provide them in `extractorInput`. These values override the defaults.

#### Analyze supplied snapshots

Use this mode with the Instagram Graph API, another Apify Actor, a data warehouse, or authorized first-party analytics. Multiple timestamps for the same Reel can be analyzed in one run.

```json
{
  "mode": "analyzeSnapshots",
  "persistHistory": false,
  "snapshots": [
    {
      "url": "https://www.instagram.com/reel/ABC123/",
      "username": "creator",
      "publishedAt": "2026-07-26T08:00:00Z",
      "collectedAt": "2026-07-26T09:00:00Z",
      "views": 1000,
      "likes": 80,
      "comments": 12,
      "followers": 15000
    },
    {
      "url": "https://www.instagram.com/reel/ABC123/",
      "username": "creator",
      "publishedAt": "2026-07-26T08:00:00Z",
      "collectedAt": "2026-07-26T10:00:00Z",
      "views": 3400,
      "likes": 240,
      "comments": 31,
      "followers": 15000
    }
  ]
}
```

Common extractor aliases are accepted, including `shortCode`, `code`, `videoPlayCount`, `playCount`, `views`, `likesCount`, `commentsCount`, `ownerUsername`, `owner.followersCount`, and several audio shapes.

### Scheduling strategy

Use the same `historyStoreName` for every scheduled run.

| Reel age | Suggested interval | Purpose |
|---|---:|---|
| 0–6 hours | 30–60 minutes | Catch early acceleration |
| 6–24 hours | 1–2 hours | Detect breakout and peak |
| 1–3 days | 3–6 hours | Estimate decay half-life |
| 4–14 days | Daily | Detect evergreen tails and revival |

The minimum spacing defaults to 15 minutes. Observations inside that window replace the preceding snapshot instead of producing unstable velocity.

### Output

```json
{
  "reelId": "ABC123",
  "url": "https://www.instagram.com/reel/ABC123/",
  "momentum": {
    "phase": "breakout",
    "viewsPerHour": 2400,
    "previousViewsPerHour": 900,
    "accelerationPct": 166.67,
    "peakViewsPerHour": 2400,
    "percentOfPeakVelocity": 100,
    "momentumScore": 78.4,
    "momentumPercentile": 100,
    "rank": 1
  },
  "decay": {
    "detected": false,
    "halfLifeHours": null,
    "modelFitR2": null,
    "estimatedPeakAt": "2026-07-26T10:00:00.000Z",
    "hoursSincePeak": 0
  },
  "forecast": {
    "viewsIn24Hours": 61000,
    "viewsIn72Hours": 176200,
    "expectedAdditionalViews24h": 57600,
    "range24h": { "low": 42000, "high": 80000 }
  },
  "opportunity": {
    "trendScore": 82.1,
    "actionWindow": "act_now",
    "recommendation": "Breakout detected. Publish a differentiated response or activate this creator immediately."
  },
  "confidence": {
    "score": 64,
    "level": "medium",
    "reasons": ["Observation window is shorter than six hours"]
  },
  "alerts": [
    {
      "type": "BREAKOUT",
      "severity": "critical",
      "message": "View velocity is breaking above its prior trajectory."
    }
  ]
}
```

Results are ranked by opportunity score in the default dataset. `OUTPUT` contains phase counts, actionable-now totals, and the ten highest-ranking opportunities.

### API usage

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/YOUR_USERNAME~instagram-reel-trend-decay-radar/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "scrape",
    "reelUrls": ["https://www.instagram.com/reel/ABC123/"],
    "historyStoreName": "my-radar"
  }'
```

Schedule the Actor in Apify Console and send critical alert records to Slack, email, a webhook, Make, or Zapier.

### Local development

Requires Node.js 22 or newer.

```bash
npm install
npm run build
npm test
```

For a no-network local run, create `storage/key_value_stores/default/INPUT.json` using `analyzeSnapshots` mode, then run:

```bash
npm run dev
```

### Model behavior and limitations

- At least two spaced snapshots are needed for velocity; three or more improve phase detection.
- A decay half-life requires at least three positive velocity intervals and a negative fitted slope.
- Forecasts are short-horizon extrapolations, not guarantees. Confidence and range widen with weak history.
- Counter drops are treated as source corrections and ignored for velocity instead of becoming negative growth.
- Within-run percentiles compare only the Reels analyzed in that run.
- Profile follower counts may be absent from extractor results; creator-normalized metrics remain `null` rather than being guessed.

### Responsible use

Use public or properly authorized data only. Do not collect private profiles, DMs, credentials, or sensitive personal data. Instagram/Meta restricts automated collection without permission; configure this Actor with a source and use case that comply with applicable platform terms, privacy law, data-retention requirements, and your contracts. The Actor deliberately separates analytics from extraction so it can work with official or first-party data.

# Actor input Schema

## `mode` (type: `string`):

Scrape calls a configurable extraction Actor. Analyze snapshots accepts metrics from any authorized source.

## `reelUrls` (type: `array`):

Individual public Instagram Reel URLs to monitor.

## `profileUrls` (type: `array`):

Public profiles whose recent Reels should be monitored.

## `snapshots` (type: `array`):

Used in Analyze snapshots mode. Each object needs a URL/shortcode and cumulative views; aliases such as playCount, videoViewCount, likesCount, and commentsCount are accepted.

## `extractorActorId` (type: `string`):

Actor called for live extraction. Override extractorInput when using a different Actor schema.

## `extractorInput` (type: `object`):

Advanced: merged over directUrls, resultsType=reels, and resultsLimit.

## `maxReelsPerProfile` (type: `integer`):

Maximum recent Reels requested for each profile.

## `historyStoreName` (type: `string`):

Named key-value store shared by scheduled runs. Keep this unchanged to preserve velocity history.

## `persistHistory` (type: `boolean`):

Required for live velocity, decay, and revival detection across scheduled runs.

## `maxHistoryPoints` (type: `integer`):

Caps storage and controls the maximum evidence trail.

## `minSnapshotSpacingMinutes` (type: `integer`):

Near-duplicate observations are replaced to prevent noisy velocity estimates.

## `alertSensitivity` (type: `string`):

Controls how large a velocity increase must be before an acceleration alert is emitted.

## `includeRawSnapshots` (type: `boolean`):

Embed normalized history in every output record. Disabled by default to keep datasets compact.

## Actor input object example

```json
{
  "mode": "analyzeSnapshots",
  "reelUrls": [
    "https://www.instagram.com/reel/EXAMPLE/"
  ],
  "profileUrls": [],
  "snapshots": [
    {
      "url": "https://www.instagram.com/reel/PULSEDECAY_DEMO/",
      "username": "pulsedecay_demo",
      "publishedAt": "2026-01-01T08:00:00.000Z",
      "collectedAt": "2026-01-01T09:00:00.000Z",
      "views": 1000,
      "likes": 80,
      "comments": 10,
      "followers": 15000
    },
    {
      "url": "https://www.instagram.com/reel/PULSEDECAY_DEMO/",
      "username": "pulsedecay_demo",
      "publishedAt": "2026-01-01T08:00:00.000Z",
      "collectedAt": "2026-01-01T10:00:00.000Z",
      "views": 2200,
      "likes": 170,
      "comments": 20,
      "followers": 15000
    },
    {
      "url": "https://www.instagram.com/reel/PULSEDECAY_DEMO/",
      "username": "pulsedecay_demo",
      "publishedAt": "2026-01-01T08:00:00.000Z",
      "collectedAt": "2026-01-01T11:00:00.000Z",
      "views": 5200,
      "likes": 390,
      "comments": 44,
      "followers": 15000
    }
  ],
  "extractorActorId": "apify/instagram-scraper",
  "extractorInput": {},
  "maxReelsPerProfile": 30,
  "historyStoreName": "reel-trend-radar-history",
  "persistHistory": true,
  "maxHistoryPoints": 120,
  "minSnapshotSpacingMinutes": 15,
  "alertSensitivity": "balanced",
  "includeRawSnapshots": false
}
```

# Actor output Schema

## `reels` (type: `string`):

Trend phase, velocity, decay, forecasts, confidence, and evidence.

## `summary` (type: `string`):

Actionable Reels, phase distribution, and top opportunities.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "reelUrls": [
        "https://www.instagram.com/reel/EXAMPLE/"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("chezsan770/instagram-reel-trend-decay-radar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "reelUrls": ["https://www.instagram.com/reel/EXAMPLE/"] }

# Run the Actor and wait for it to finish
run = client.actor("chezsan770/instagram-reel-trend-decay-radar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "reelUrls": [
    "https://www.instagram.com/reel/EXAMPLE/"
  ]
}' |
apify call chezsan770/instagram-reel-trend-decay-radar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=chezsan770/instagram-reel-trend-decay-radar",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/CHvbbDKYaCpNRtIGx/builds/nNfILIpSYQokqRwHK/openapi.json