Viral Trends API

When to use it

• Content automation agents that need to pick "what to write about today" without a human picking topics.
• News-driven workflows where post timing matters more than ever-green content.
• Multi-platform schedulers that want platform-aware trending topics (TikTok-viral vs LinkedIn-viral vs YouTube-viral) ranked together.
• Newsroom dashboards that need a single rolled-up trending feed instead of querying 5 separate platform APIs.

Endpoints

• GET /api/v1/trends/radar — Ranked trending topics with virality score
• GET /api/v1/trends/breaking — Breaking news only, sorted by urgency
• POST /api/v1/news-broadcast/recommend — Given a brand profile + platform, recommend today's best 3 stories

Quickstart

curl "https://api.reelsbuilder.ai/api/v1/trends/radar?geo=US&category=tech&limit=10" \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

Response shape

{
  "success": true,
  "data": {
    "trends": [
      {
        "id": "tr_01HKZ9N...",
        "topic": "OpenAI ships realtime voice",
        "virality_score": 0.92,
        "urgency": "breaking",
        "started_at": "2026-05-15T18:42:00.000Z",
        "recency_hours": 2,
        "traffic_estimate": "1M+",
        "source_signals": ["google_trends", "newsapi", "twitter_top"],
        "platforms": {
          "tiktok_relevance": 0.78,
          "youtube_relevance": 0.91,
          "linkedin_relevance": 0.88,
          "instagram_relevance": 0.72
        },
        "sources": [
          { "title": "OpenAI launches realtime voice API", "url": "https://...", "domain": "techcrunch.com" }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_...",
    "credits_used": 2,
    "credits_remaining": 998,
    "next_refresh_at": "2026-05-15T20:42:00.000Z"
  }
}

Parameters

How the virality score works

Every trend is scored 0.0–1.0 based on five orthogonal signals, combined with a weighted average:

1. Search momentum (Google Trends search volume velocity in the recency window)
2. News density (count of independent publishers covering the topic in the same window)
3. Social signal (engagement velocity on the source URLs, derived from our crawl)
4. Novelty (penalty for topics that have been trending for >6 hours — protects against stale viral content)
5. Quality (boost for trends sourced from primary publishers, penalty for purely aggregator-driven trends)

A score of 0.9+ is "you should make content right now." 0.7–0.9 is "worth covering today." Below 0.5 is filtered by default.

Examples

TypeScript

const params = new URLSearchParams({
  geo: "US",
  category: "tech",
  limit: "5",
  min_virality: "0.8",
});

const res = await fetch(
  `https://api.reelsbuilder.ai/api/v1/trends/radar?${params}`,
  {
    headers: {
      Authorization: `Bearer ${process.env.REELSBUILDER_API_KEY}`,
    },
  },
);
const { data } = await res.json();
for (const trend of data.trends) {
  console.log(`[${trend.virality_score}] ${trend.topic} (${trend.recency_hours}h)`);
}

Python

import os, requests

r = requests.get(
    "https://api.reelsbuilder.ai/api/v1/trends/radar",
    params={"geo": "US", "category": "tech", "limit": 5, "min_virality": 0.8},
    headers={"Authorization": f"Bearer {os.environ['REELSBUILDER_API_KEY']}"},
)
for trend in r.json()["data"]["trends"]:
    print(f"[{trend['virality_score']}] {trend['topic']} ({trend['recency_hours']}h)")

Breaking news endpoint

GET /api/v1/trends/breaking is a tighter view of the radar filtered to urgency=breaking trends in the last 18 hours. Same response shape; ordered by urgency + recency_hours ascending.

curl "https://api.reelsbuilder.ai/api/v1/trends/breaking?windowHours=18" \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY"

Brand-aware recommendation

POST /api/v1/news-broadcast/recommend combines Viral Trends with your Brand DNA profile and returns the 3 trends most relevant to your audience.

curl -X POST https://api.reelsbuilder.ai/api/v1/news-broadcast/recommend \
  -H "Authorization: Bearer $REELSBUILDER_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "brn_01HKZ...",
    "platform": "tiktok",
    "count": 3
  }'

Pricing

• /trends/radar — 2 credits per call (1 if cached within 10 min).
• /trends/breaking — 2 credits per call.
• /news-broadcast/recommend — 5 credits per call (includes brand match scoring).

Free accounts include fixed starter videos, not a radar-call credit balance. See rate limits for per-plan ceilings.

Caching

Radar results are cached at the source level for 10 minutes per (geo + category) combination. Repeated calls within the window return the same trend set at the cached credit rate (1 credit). The next_refresh_at field in meta tells you when fresh data is next available.

Composing with other endpoints

The most common chain:

1. GET /trends/radar → pick one high-virality topic
2. POST /hooks/generate → get 5 ranked hooks for that topic (see Hook Generator)
3. POST /generate-and-post → produce + distribute a branded short-form video (see Generate & Post)

Total cost: ~25 credits, ~3-minute end-to-end latency. The whole loop runs under a single Idempotency-Key chain.

See also

• Hook Generator API
• Brand DNA API
• Generate & Post API