Documentation

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/youtube/channel/id?url=https://www.youtube.com/@channelname"

Response:

{
  "data": "UCxxxxxxxxxxxxxxxxxxxxxx",
  "meta": {
    "cost": 1,
    "remaining": 999,
    "cached": false
  }
}

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. Most endpoints cost 1 credit. /api/v1/youtube/channel (full statistics) costs 2 credits. Credits do not expire.

Refunds. If a request fails because of an error on our side (5xx), or the upstream returns "not found", credits are not charged.

Cost by endpoint

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

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: 1.",
    "details": { "balance": 0, "required": 1 }
  }
}

Status codes

Response format

Successful responses always have data and meta:

{
  "data": ...,
  "meta": {
    "cost": 1,
    "remaining": 999,
    "cached": false
  }
}

• data. The result. A number, string, or object depending on the endpoint. Numeric values are returned as JSON numbers (not strings).
• meta.cost. Credits charged for this request.
• meta.remaining. Credit balance after the charge.
• meta.cached. true if served from cache. Still charged.