# 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

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

```bash
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

```json
{
  "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:

```json
  "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 |