API Reference

Documentation

42 REST endpoints across 14 platforms. One schema, one authentication scheme, one response shape. Built around publicly available information.

Quickstart

  1. 1
    Create an account and top up credits from the pricing page.
  2. 2
    Generate an API key on the API keys page. Copy it once. We only keep a SHA-256 hash.
  3. 3
    Make your first request:
curl -H "Authorization: Bearer ts_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  "https://tubestat.co/api/v1/tiktok/user?url=https://www.tiktok.com/@username"

Response:

{
  "data": {
    "userId": "6557092804635377669",
    "username": "username",
    "followers": 3442387,
    "following": 169,
    "likes": 210580901,
    "videos": 676
  },
  "meta": {
    "cost": 2,
    "remaining": 998,
    "cached": false,
    "requestId": "a3f1c9e20b4d7a55"
  }
}
Every endpoint takes exactly one parameter: url. Point it at the page you would open in a browser and we return the counters for it.

Authentication

Every request must include an Authorization header with a Bearer API key:

Authorization: Bearer ts_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys start with ts_live_ and are 40 characters long. We only store a SHA-256 hash on our side. If you lose a key, generate a new one and revoke the old one from the API keys page.

Keep keys secret. Do not commit them to public repositories, and do not ship them in browser side JavaScript.

Credits and pricing

Requests are paid in credits, and the price depends on how much you ask for:

  • 2 credits for the full object. You get every field the endpoint supports.
  • 1 credit for a single field, using ?field=.

The price is the same on every platform. Credits do not expire.

Refunds. If a request fails for any reason other than your own input, credits are refunded automatically. You only pay for data you actually receive.

Cached responses still cost credits. You are paying for the data, not the bandwidth.

Selecting a single field

If you only need one number, add ?field= and pay 1 credit instead of 2. The body collapses to that value:

GET /api/v1/tiktok/user?url=...&field=followers

{ "data": 3442387, "meta": { "cost": 1, "field": "followers", ... } }
Need several fields from the same endpoint? Ask for the full object once. Three ?field= calls cost 3 credits and return the same data the 2 credit full call already contains.

An unknown field name returns 400 unknown_field together with the list of valid fields for that endpoint, and is not charged.

Values, nulls and precision

null and 0 are different

This distinction matters more than any other in the API:

  • null. The platform does not expose this value. A hidden like counter, a private account.
  • 0. A real zero. The platform told us, and the answer is zero.
  • Key absent. The field does not apply to this particular target.

Treating null as 0 means reporting that an account lost all of its followers when in fact you simply do not know. We never substitute one for the other.

Rounded versus exact

Some platforms publish rounded counters. YouTube subscriber counts, for example, are rounded to three significant digits at the source, while video counts are exact. When a response contains rounded values we say so per field:

"meta": {
  "precision": { "followers": "rounded", "videos": "exact", "views": "exact" }
}

Use this before building comparisons or growth reports. Two numbers with different precision are not directly comparable.

Units

  • Durations are always milliseconds (durationMs).
  • Timestamps are always ISO-8601 UTC (2009-10-25T06:57:33Z).
  • Counters are always JSON numbers, never strings.

Rate limits

Each API key is limited to 60 requests per minute. Exceeding this returns HTTP 429 with a Retry-After header.

Need higher throughput? Email [email protected].

Errors

All errors return a consistent JSON body:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Balance: 0, required: 2.",
    "details": { "balance": 0, "required": 2 }
  }
}

Status codes

StatusCodeMeaningCharged
400missing_urlThe url query parameter is missing.No
400invalid_urlThe URL does not match the format this endpoint expects.No
400unknown_fieldThe field value is not valid for this endpoint.No
400unsupported_requestThis target or field is not available on this endpoint.No
401unauthorizedNo Authorization header was sent.No
401invalid_api_keyThe API key was malformed, revoked, or not found.No
402insufficient_creditsBalance is lower than the endpoint cost.No
404not_foundThe target does not exist, or it is private.Refunded
429rate_limitedYou exceeded 60 requests per minute.No
429upstream_rate_limitedThe source platform is rate limiting us. Retry shortly.Refunded
502upstream_errorSomething failed on our side.Refunded
503upstream_unavailableTemporarily unavailable. Retry shortly.Refunded
504upstream_timeoutThe lookup took too long.Refunded

Include meta.requestId (success) or the time of the call when contacting support. It lets us find the exact request.

Response format

Successful responses always have data and meta:

{
  "data": ...,
  "meta": {
    "cost": 2,
    "remaining": 998,
    "cached": false,
    "requestId": "a3f1c9e20b4d7a55",
    "precision": { "followers": "rounded" }
  }
}
  • data. An object for a full request, a single value when ?field= is used.
  • meta.cost. Credits charged for this request.
  • meta.remaining. Credit balance after the charge.
  • meta.cached. true if served from cache. Still charged.
  • meta.requestId. Identifier for this request. Quote it in support requests.
  • meta.precision. Present when at least one value is rounded at the source.
  • meta.field. Present when ?field= was used.

Endpoints by platform

Every platform follows the same contract described above. Pick one to see its endpoints, fields and worked examples.