Detect viral posts via API — velocity monitoring for YouTube, X, TikTok

How-to

Detect viral posts via API — velocity monitoring for YouTube, X, TikTok, Bluesky

A single metrics read tells you where a post is. What a monitoring alert, a trend dashboard, or an "is this going viral?" check actually needs is where it's going — the velocity. Pulse stores a snapshot every time you fetch a post, so repeated reads accumulate a series automatically. The /history endpoint returns the growth curve plus pre-computed velocity — views per hour, likes per hour — with no database setup and no cron job.

How velocity works

curl "https://pulse.walls.sh/history?url=https://www.youtube.com/watch?v=dQw4w9WgXcQ"

{
  "platform": "youtube",
  "kind": "post",
  "count": 181,
  "latest": { "views": 1781821814, "likes": 19151227 },
  "delta": {
    "hours_elapsed": 43.78,
    "views": 641676,
    "likes": 3649
  },
  "velocity": {
    "views_per_hour": 14656.5,
    "likes_per_hour": 83.35
  }
}

181 snapshots accumulated over 43 hours of regular polling. Rick Astley's "Never Gonna Give You Up" is gaining ~14,600 views per hour — a viral signal for a 15-year-old video. The velocity field is computed from all stored snapshots so you don't have to keep track of the previous value yourself.

Set up monitoring in Python

import requests, time

WATCH = [
    "https://www.tiktok.com/@creator/video/123456",
    "https://bsky.app/profile/someone.bsky.social/post/abc123",
    "https://x.com/handle/status/123456",
]
VIRAL_THRESHOLD = 1000  # views/hour

while True:
    for url in WATCH:
        hist = requests.get("https://pulse.walls.sh/history", params={"url": url}).json()
        vph = hist.get("velocity", {}).get("views_per_hour") or 0
        if vph > VIRAL_THRESHOLD:
            print(f"VIRAL: {url} → {vph:.0f} views/hour")
        # /metrics call records a new snapshot for the history
        requests.get("https://pulse.walls.sh/metrics", params={"url": url})
    time.sleep(3600)  # poll every hour

Poll only the delta — not the full series

For posts with long histories, use since= to fetch only new snapshots since the last check. This is efficient even if the post has thousands of points:

from datetime import datetime, timezone, timedelta

since = (datetime.now(timezone.utc) - timedelta(hours=1)).isoformat()
hist = requests.get("https://pulse.walls.sh/history", params={
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "since": since
}).json()
# Only points from the last hour — not the full 181-point series

Use in an AI agent

The pulse-mcp server exposes a history tool. Ask Claude: "Is @creator's latest TikTok going viral?" — the agent calls history({ url: "..." }) and interprets the velocity numbers.

Viral thresholds by platform

What counts as "viral" varies by platform size and content type. A rough guide based on typical growth rates:

Platform	Metric	Growing	Viral
YouTube	views/hr	>1,000	>50,000
TikTok	views/hr	>5,000	>100,000
X / Twitter	likes/hr	>100	>10,000
Bluesky	likes/hr	>20	>500

These are illustrative — calibrate thresholds to the specific account size and content type you're monitoring.

Rate limits and pricing

Free: 120 calls/minute. For always-on monitoring pipelines checking dozens of posts every hour, the $19/mo Pro plan raises the ceiling to 1,200 calls/minute (10×) with commercial terms — see pricing or sign up at /account.

More: full API docs · OpenAPI spec · track a post's growth curve · calculate engagement rate · all supported platforms.