One key, one base URL, plain JSON. Pull views, likes, followers and the U.S. country split from every account we run for you — straight into your dashboard, your warehouse or your client reports.
Your key is issued by us and already waiting — you don't request it here. Paste it into the dashboard to see your numbers, or into your own code to pull them.
Everything is a GET. Everything returns JSON. There is nothing to install.
# 1. Check the key works curl https://viranomix.com/api/v1/me \ -H "Authorization: Bearer vrx_live_YOUR_KEY" # 2. List the accounts on your key curl https://viranomix.com/api/v1/accounts \ -H "Authorization: Bearer vrx_live_YOUR_KEY" # 3. Pull the last 30 days for one of them curl "https://viranomix.com/api/v1/accounts/acc_9f3k2m8qz1xv/metrics?from=2026-09-01" \ -H "Authorization: Bearer vrx_live_YOUR_KEY"
https://viranomix.com/api/v1 — one environment, always HTTPS. Requests over plain HTTP are redirected.
JSON in, JSON out. Timestamps are ISO 8601 in UTC. Counters are integers, never strings.
The API cannot post, delete or change anything. A leaked key exposes your numbers, never your accounts.
We issue the key. It is shown to you once and stored only as a hash on our side — if you lose it, we issue a new one rather than recovering the old one.
# Preferred Authorization: Bearer vrx_live_xxxxxxxxxxxxxxxxxxxx # Equivalent, for tools that can't set an Authorization header X-API-Key: vrx_live_xxxxxxxxxxxxxxxxxxxx
In your backend, or in your dashboard — both are fine, because the key is yours and read-only. What you must not do is ship it inside a public website's source or a mobile app binary, where anyone viewing the page can lift it. Need one key per client, per environment or per developer? Ask — we issue as many as you want, each revocable on its own.
Ten of them. If you need an eleventh shaped the way your system wants it, that is a conversation, not a ticket.
What this key can do: your plan, how many accounts it reaches, which KPIs are switched on, and your rate limits. Good first call when wiring up an integration.
{
"client": { "name": "Jane's Agency", "plan": "growth", "status": "active" },
"key": { "label": "production", "prefix": "vrx_live_8sK2mQ", "last4": "9fQ2" },
"access": {
"accounts": 14,
"kpis": ["follower_count", "view_count", "like_count", "us_share"],
"history_days": 90,
"rate_per_min": 60
}
}
Every account assigned to your key, with its latest profile numbers.
Query: limit (1–200, default 50), offset, search, status.
{
"data": [
{
"id": "acc_9f3k2m8qz1xv",
"platform": "tiktok",
"username": "brandusa",
"display_name": "Brand USA",
"profile_url": "https://www.tiktok.com/@brandusa",
"status": "active",
"follower_count": 18422,
"likes_count": 241890,
"video_count": 312,
"last_synced_at": "2026-09-30T08:14:02+00:00"
}
],
"pagination": { "total": 14, "limit": 50, "offset": 0, "has_more": false }
}
One account, plus follower_growth — the change since the previous snapshot.
A daily time series for one account. Query: from, to (YYYY-MM-DD or ISO). Defaults to the last 30 days, and is clipped to the history window on your plan.
{
"account_id": "acc_9f3k2m8qz1xv",
"granularity": "day",
"data": [
{ "date": "2026-09-28", "follower_count": 18201, "follower_growth": 142 },
{ "date": "2026-09-29", "follower_count": 18310, "follower_growth": 109 }
]
}
Videos for one account, newest first, with their current metrics and a computed engagement_rate.
Query: limit (1–100), offset, since.
{
"data": [
{
"id": "vid_7k2m9qz1xv3f",
"account_id": "acc_9f3k2m8qz1xv",
"title": "3 things nobody tells you about…",
"share_url": "https://www.tiktok.com/@brandusa/video/7k2m9qz1xv3f",
"posted_at": "2026-09-27T16:03:11+00:00",
"view_count": 84210,
"like_count": 6120,
"comment_count": 318,
"share_count": 402,
"engagement_rate": 8.128
}
],
"pagination": { "total": 312, "limit": 25, "offset": 0, "has_more": true }
}
The country split — the number the whole service exists for. Returns us_share as a percentage and, if enabled on your key, the full country list.
{
"account_id": "acc_9f3k2m8qz1xv",
"captured_date": "2026-09-30",
"us_share": 94.2,
"countries": [
{ "country_code": "US", "percentage": 94.2 },
{ "country_code": "CA", "percentage": 2.8 }
]
}
A single video by its Viranomix id.
How one video accumulated views, likes, comments and shares day by day. Query: from, to.
One call for a whole reporting dashboard: totals across every account on your key. Query: days (1–365, default 30).
{
"period_days": 30,
"accounts": 14,
"videos": 268,
"follower_count": 204118,
"view_count": 4192044,
"like_count": 288104,
"avg_us_share": 93.4
}
Liveness check. The only endpoint that does not need a key.
Each key has its own list of enabled KPIs. Anything not on your list is removed from the response before it leaves our server — so a field you do not have never appears, even empty. Call /v1/me to see your exact list.
| Field | Where | What it is |
|---|---|---|
| follower_count | account | Followers at the last sync. |
| following_count | account | Accounts this one follows. |
| likes_count | account | Lifetime likes across the profile. |
| video_count | account | Public videos on the profile. |
| follower_growth | account | Change since the previous snapshot. Computed by us. |
| view_count | video | Cumulative views. |
| like_count | video | Likes. |
| comment_count | video | Comments. |
| share_count | video | Shares. |
| engagement_rate | video | (likes + comments + shares) ÷ views, as a percentage. Computed by us. |
| title | video | Caption text. |
| share_url | video | Public link to the video. |
| posted_at | video | When it went out, UTC. |
| duration_sec | video | Length in seconds. |
| cover_image_url | video | Thumbnail. TikTok expires these — fetch and re-host if you need them to last. |
| us_share | audience | Percentage of viewers in the United States. |
| audience_countries | audience | The full country breakdown. |
Account and video metrics are collected on a rolling schedule and are typically under two hours old; every payload carries last_synced_at or metrics_updated_at so you can show the real age rather than guess. Audience data updates about once a day — TikTok itself only recalculates the country split periodically, and needs recent activity on a video before it reports one at all.
Switch on error.code, show error.message. Never parse the prose.
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "That API key is not recognised.",
"docs": "https://viranomix.com/api"
}
}
| Status | Code | Means |
|---|---|---|
| 401 | missing_api_key | No key on the request. |
| 401 | invalid_api_key | The key does not exist. |
| 401 | revoked_api_key | The key was revoked. Ask us for a new one. |
| 403 | client_inactive | The account behind the key is paused or cancelled. |
| 403 | kpi_not_enabled | You asked for data your key is not configured for. |
| 404 | account_not_found | No such account, or it is not assigned to your key. |
| 404 | video_not_found | Same, for a video. |
| 405 | method_not_allowed | The API is read-only. Use GET. |
| 429 | rate_limit_exceeded | Too many requests this minute. See Retry-After. |
| 429 | daily_quota_exceeded | Rolling 24-hour quota used up. |
Defaults are 60 requests a minute and 10,000 a day per key. Every successful response tells you where you stand, so you never have to guess.
X-RateLimit-Limit: 60 X-RateLimit-Remaining: 57 X-RateLimit-Limit-Day: 10000 X-RateLimit-Remaining-Day: 9873
List endpoints take limit and offset and return a pagination block with has_more. Loop on that, not on a guessed page count.
The underlying data refreshes on a schedule measured in hours. Polling every minute costs you quota and returns the same numbers.
One call instead of a loop over every account when all you need is the headline figures for a dashboard.
Limits are set per key, and we raise them on request. If you are backfilling a warehouse or running a nightly export across hundreds of accounts, tell us the shape of the job and we will size the key for it instead of letting you discover the ceiling in production.
This reference is the standard surface. It is not the limit of what you can have.
Rather be pushed to than poll? We can post to your endpoint when a video lands or a sync completes.
A different JSON structure, a flat CSV drop, a nightly file in your bucket, fields renamed to match your schema — all fine.
It is a plain REST API with a bearer token, so Make, n8n, Zapier, Google Sheets and Power BI all connect without a custom connector.
Book the call and bring your developer, or send the spec. Tell us what your system speaks and we will build the integration around it rather than asking you to rebuild anything. Available on every plan — scoped with you on the call.
Paste it into the dashboard and your numbers are on screen in about five seconds. No key yet? Fifteen minutes on a call and you'll have one the same day.