GET /v1/usage

Per-key calls and cost for a day. A consumer key sees its own usage; the admin token sees every key. Cost is computed live at query time, never stored.

Request

curl "https://tikdata.io/v1/usage" -H "Authorization: Bearer thr_live_xxx"

curl "https://tikdata.io/v1/usage?day=2026-09-07" -H "x-admin-token: $INGEST_TOKEN"

param	default	notes
day	today	YYYY-MM-DD in America/Los_Angeles, the upstream billing boundary. Not UTC.

Response — 200

{
  "day": "2026-09-08",
  "scope": "this key",
  "pricing": {
    "source": "live",
    "note": "priced against today's live account volume"
  },
  "totals": { "calls": 27, "cost": 0.0269 },
  "keys": [
    {
      "keyId": "rk_125d066d94a7",
      "project": "market-bubble",
      "calls": 27,
      "cost": 0.0269,
      "byEndpoint": [
        { "uri": "/api/v1/twitter/web/fetch_user_media", "count": 6,
          "unitPrice": 0.001, "cost": 0.006 },
        { "uri": "/api/v1/tiktok/app/v3/fetch_one_video", "count": 3,
          "unitPrice": 0.000923, "cost": 0.002769 }
      ]
    }
  ]
}

With the admin token, an extra block compares tracked spend to the real account meter:

  "account": {
    "day": "2026-09-08",
    "spend": 16.7964,
    "requests": 17093,
    "trackedShare": 0.000174
  }

field	notes
scope	"this key" or "all keys"
pricing.note	whether the account's live volume was available for the requested day (see below)
keys[].byEndpoint[].unitPrice	the discounted per-call rate actually applied, given account volume that day
account.trackedShare	this deployment's share of the account's real spend; consumers never see this block

byEndpoint is capped at 20 entries per key, highest cost first.

Why cost is computed, not stored

The upstream's volume discounts are progressive and account-wide — 0/10/20/30/40/50% at 1k/5k/10k/20k/30k requests per endpoint per day, applied to the slice in each tier. So the same three calls cost less on a day the account was busy than on a quiet one, and a key's true rate depends on what every other consumer did that day. A price written down at call time would be wrong by the time the day closed.

Instead, per-key counts are stored, and this endpoint prices them at read time against three live sources — the price catalogue, the discount tiers, and the account's real per-endpoint volume for the day. unitPrice shows the result: at 5,551 calls in a day, fetch_tweet_detail prices at $0.000908, not its $0.001 base.

Past days are approximate

The upstream meter only ever reports the current day. A past day is therefore priced against today's tiers, and pricing.note says so:

"account volume is only available for the current day; priced against today's tiers"

Errors

status	body
400	{"error":"day must be YYYY-MM-DD","hint":"days are America/Los_Angeles, TikHub's billing boundary"}
401	no valid key and no admin token
502	{"error":"could not price usage","hint":"..."} — the live price catalogue or tiers could not be fetched