API Reference
Documentation
42 REST endpoints across 14 platforms. One schema, one authentication scheme, one response shape. Built around publicly available information.
Quickstart
-
1
Create an account and top up credits from the pricing page.
-
2
Generate an API key on the API keys page. Copy it once. We only keep a SHA-256 hash.
-
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"
}
}
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.
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", ... } }
?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
| Status | Code | Meaning | Charged |
|---|---|---|---|
| 400 | missing_url | The url query parameter is missing. | No |
| 400 | invalid_url | The URL does not match the format this endpoint expects. | No |
| 400 | unknown_field | The field value is not valid for this endpoint. | No |
| 400 | unsupported_request | This target or field is not available on this endpoint. | No |
| 401 | unauthorized | No Authorization header was sent. | No |
| 401 | invalid_api_key | The API key was malformed, revoked, or not found. | No |
| 402 | insufficient_credits | Balance is lower than the endpoint cost. | No |
| 404 | not_found | The target does not exist, or it is private. | Refunded |
| 429 | rate_limited | You exceeded 60 requests per minute. | No |
| 429 | upstream_rate_limited | The source platform is rate limiting us. Retry shortly. | Refunded |
| 502 | upstream_error | Something failed on our side. | Refunded |
| 503 | upstream_unavailable | Temporarily unavailable. Retry shortly. | Refunded |
| 504 | upstream_timeout | The 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.trueif 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.