● Included in the Agency plan

Viral trend data, as an API

One REST API for TikTok, Instagram and YouTube: ranked viral videos, growth curves, trending hashtags, top creators and your own agents’ matches, plus webhooks that push new matches to you.

Create keys in your Agency workspace. Not on Agency yet? See plans

Quickstart
curl "https://vosscore.com/api/v1/feed?platform=tiktok&sort=newest&dateRange=24h&limit=10" \
  -H "X-API-Key: $VOSSCORE_API_KEY"

🔑 Authentication

Send your key on every request in the X-API-Key header. A Bearer header works too. Keep keys on your server, never in a browser or app.

X-API-Key: vsk_••••••••••••••••
# or
Authorization: Bearer vsk_••••••••••••••••

Base URL: https://vosscore.com/api/v1

📦 Video object

{
  "id": "tt_7627486...",
  "platform": "tiktok",
  "title": "...",
  "author": "hirsizkedi",
  "url": "https://www.tiktok.com/@.../video/...",
  "thumbnailUrl": "https://...",
  "views": 1200000,
  "likes": 42700,
  "comments": 812,
  "shares": 3100,
  "durationSec": 21,
  "hashtags": ["cat", "funny"],
  "publishedAt": "2026-10-27T09:14:00.000Z",
  "collectedAt": "2026-10-28T02:40:11.000Z",
  "vosscoreUrl": "https://vosscore.com/trend/tt_...",
  "embeddable": true
}

embeddable: false means the platform does not allow this video to be embedded on other sites. The data is still valid; link to the url instead of embedding it.

Endpoints

All endpoints are GET and return JSON.

GET/feedViral videos from the pool, ranked by views or by arrival time.
platformtiktok | instagram | youtube | allDefault: all
sortviews | newestnewest = most recently added to the pool
dateRange24h | 7d | 30d | 90dOnly videos added to the pool in this window
minViewsintegerMinimum view count
limit1–100Default: 20
page1–50Default: 1
GET/videos/{id}A single video. Add history=1 for its growth snapshots (views, likes, comments over time).
history1Include the growth curve
GET/hashtags/trendingHashtags ranked by total views of videos that entered the pool in the window. Platform-wide tags like #fyp are left out.
platformtiktok | instagram | youtube | allDefault: all
days1–60Default: 30
limit1–100Default: 30
GET/creators/topCreators whose videos brought the most views into the pool in the window.
platformtiktok | instagram | youtube | allDefault: all
days1–90Default: 30
limit1–100Default: 20
GET/agentsYour agents (the topics you track) with their terms and settings.
GET/agents/{id}/matchesEvery video in the pool that matches one of your agents.
sortnewest | views | outlieroutlier = performing far above similar videos
limit1–100Default: 48
page1–100Default: 1
GET/usageYour key’s hourly limit, requests used this hour and when the window resets.

Rate limits

Each key can make 1,000 requests per hour, and you can create up to 5 keys. Every response tells you where you stand. Need more? Agency accounts can get a custom limit: reply to any of our emails with your expected volume.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1793782800   # unix seconds
Retry-After: 1260               # only on 429

Errors

400invalid_platform · invalid_dateRangeA parameter has a value we don’t accept. The response lists the allowed values.
401api_key_required · invalid_api_keyThe key is missing, mistyped or has been deleted.
403plan_requiredThe account that owns the key is no longer on the Agency plan.
404not_foundNo video or agent with that id on your account.
429rate_limit_exceededHourly limit reached. Wait for the time in Retry-After.

Webhooks

Add a webhook URL to any agent (agent settings → Webhook URL). Each time new videos match that agent, we POST them to you, no polling needed. Slack, Discord and DingTalk robot links get a ready-made message (DingTalk: set the robot’s security keyword to “Vosscore”, allow IP 164.92.244.151, or add &secret=SEC… to the URL for signing); any other HTTPS endpoint gets the signed JSON below. Use “Send test” in the agent settings to try it.

Payload · agent.new_matches

POST https://your-endpoint.com/hooks
Content-Type: application/json
X-Vosscore-Event: agent.new_matches
X-Vosscore-Timestamp: 1793781234
X-Vosscore-Signature: sha256=5f2c...

{
  "event": "agent.new_matches",
  "test": false,
  "sentAt": "2026-11-04T10:00:00.000Z",
  "agent": { "id": "...", "name": "Street food",
             "keywords": [...], "hashtags": [...],
             "platforms": [...], "url": "..." },
  "count": 3,
  "items": [ /* video objects */ ]
}

Answer with any 2xx within 10 seconds. Redirects are not followed.

Verify the signature

Your signing secret is in the Agency workspace. Compute an HMAC-SHA256 of "timestamp.body" and compare it with the header.

const crypto = require("crypto");
// rawBody: the request body exactly as received
const ts = req.headers["x-vosscore-timestamp"];
const expected = "sha256=" + crypto
  .createHmac("sha256", process.env.VOSSCORE_WEBHOOK_SECRET)
  .update(ts + "." + rawBody)
  .digest("hex");
const got = String(req.headers["x-vosscore-signature"] || "");
const valid = got.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));

Build on Vosscore

The REST API, webhooks and 5 team seats come with the Agency plan. Create your first key in a minute.