Open your dashboard ↗
Viranomix Data API · v1

Your U.S. Account Data, In Your Own Stack

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.

Open your dashboard › Build an integration

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.

✓ Read-only ✓ No extra charge ✓ Custom endpoints on request
Quickstart

Two Minutes To First Response

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"
🔑

Base URL

https://viranomix.com/api/v1 — one environment, always HTTPS. Requests over plain HTTP are redirected.

📦

Format

JSON in, JSON out. Timestamps are ISO 8601 in UTC. Counters are integers, never strings.

🔒

Read-only

The API cannot post, delete or change anything. A leaked key exposes your numbers, never your accounts.

Authentication

One Secret Key, Two Ways To Send It

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

Where to put the key

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.

Reference

Endpoints

Ten of them. If you need an eleventh shaped the way your system wants it, that is a conversation, not a ticket.

GET/v1/me

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
  }
}
GET/v1/accounts

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 }
}
GET/v1/accounts/{account_id}

One account, plus follower_growth — the change since the previous snapshot.

GET/v1/accounts/{account_id}/metrics

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 }
  ]
}
GET/v1/accounts/{account_id}/videos

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 }
}
GET/v1/accounts/{account_id}/audience

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 }
  ]
}
GET/v1/videos/{video_id}

A single video by its Viranomix id.

GET/v1/videos/{video_id}/metrics

How one video accumulated views, likes, comments and shares day by day. Query: from, to.

GET/v1/summary

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
}
GET/v1/ping

Liveness check. The only endpoint that does not need a key.

Fields

You Only Get The Fields You Signed Up For

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.

FieldWhereWhat it is
follower_countaccountFollowers at the last sync.
following_countaccountAccounts this one follows.
likes_countaccountLifetime likes across the profile.
video_countaccountPublic videos on the profile.
follower_growthaccountChange since the previous snapshot. Computed by us.
view_countvideoCumulative views.
like_countvideoLikes.
comment_countvideoComments.
share_countvideoShares.
engagement_ratevideo(likes + comments + shares) ÷ views, as a percentage. Computed by us.
titlevideoCaption text.
share_urlvideoPublic link to the video.
posted_atvideoWhen it went out, UTC.
duration_secvideoLength in seconds.
cover_image_urlvideoThumbnail. TikTok expires these — fetch and re-host if you need them to last.
us_shareaudiencePercentage of viewers in the United States.
audience_countriesaudienceThe full country breakdown.

How fresh is it?

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.

Errors

Every Failure Has The Same Shape

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"
  }
}
StatusCodeMeans
401missing_api_keyNo key on the request.
401invalid_api_keyThe key does not exist.
401revoked_api_keyThe key was revoked. Ask us for a new one.
403client_inactiveThe account behind the key is paused or cancelled.
403kpi_not_enabledYou asked for data your key is not configured for.
404account_not_foundNo such account, or it is not assigned to your key.
404video_not_foundSame, for a video.
405method_not_allowedThe API is read-only. Use GET.
429rate_limit_exceededToo many requests this minute. See Retry-After.
429daily_quota_exceededRolling 24-hour quota used up.
Rate limits

Limits You Will Probably Never Hit

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
📄

Paginate

List endpoints take limit and offset and return a pagination block with has_more. Loop on that, not on a guessed page count.

⏱️

Poll sensibly

The underlying data refreshes on a schedule measured in hours. Polling every minute costs you quota and returns the same numbers.

📊

Use /summary

One call instead of a loop over every account when all you need is the headline figures for a dashboard.

Need more?

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.

Custom integrations

If It Isn't Here, We'll Build It

This reference is the standard surface. It is not the limit of what you can have.

🔗

Webhooks

Rather be pushed to than poll? We can post to your endpoint when a video lands or a sync completes.

🧩

Your shape, not ours

A different JSON structure, a flat CSV drop, a nightly file in your bucket, fields renamed to match your schema — all fine.

⚙️

No-code tools

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.

How to ask

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.

Get started

Already Have A Key? Use It.

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.

Open your dashboard › Book a call
API access included on every plan · No extra charge