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
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.
/feedViral videos from the pool, ranked by views or by arrival time.| platform | tiktok | instagram | youtube | all | Default: all |
| sort | views | newest | newest = most recently added to the pool |
| dateRange | 24h | 7d | 30d | 90d | Only videos added to the pool in this window |
| minViews | integer | Minimum view count |
| limit | 1–100 | Default: 20 |
| page | 1–50 | Default: 1 |
/videos/{id}A single video. Add history=1 for its growth snapshots (views, likes, comments over time).| history | 1 | Include the growth curve |
/hashtags/trendingHashtags ranked by total views of videos that entered the pool in the window. Platform-wide tags like #fyp are left out.| platform | tiktok | instagram | youtube | all | Default: all |
| days | 1–60 | Default: 30 |
| limit | 1–100 | Default: 30 |
/creators/topCreators whose videos brought the most views into the pool in the window.| platform | tiktok | instagram | youtube | all | Default: all |
| days | 1–90 | Default: 30 |
| limit | 1–100 | Default: 20 |
/agentsYour agents (the topics you track) with their terms and settings./agents/{id}/matchesEvery video in the pool that matches one of your agents.| sort | newest | views | outlier | outlier = performing far above similar videos |
| limit | 1–100 | Default: 48 |
| page | 1–100 | Default: 1 |
/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
| 400 | invalid_platform · invalid_dateRange | A parameter has a value we don’t accept. The response lists the allowed values. |
| 401 | api_key_required · invalid_api_key | The key is missing, mistyped or has been deleted. |
| 403 | plan_required | The account that owns the key is no longer on the Agency plan. |
| 404 | not_found | No video or agent with that id on your account. |
| 429 | rate_limit_exceeded | Hourly 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.