Feature request: expose free-model daily usage counter in the API (e.g. /api/v1/key)

[faithpricejp-source]

Summary

There is currently no public API to learn how many free-model (:free) requests an account has used today against its daily cap. Users only discover their position when they hit a 429 mid-session.

Background

Per the FAQ, free models are rate-limited to 20 requests/minute and a daily cap of 50 requests/day — raised to 1000 requests/day for accounts that have purchased at least 10 credits. This makes "how many of my 1000 free requests are left today" a first-class quota for a large class of users who top up credits but only consume free models.

Current state

• GET /api/v1/key returns spend-centric fields (usage_daily, usage_weekly, usage_monthly, limit_remaining) and a rate_limit object explicitly marked "This field is deprecated and safe to ignore." — no free-request counter.
• GET /api/v1/activity only serves completed UTC days; requesting the current day returns HTTP 400, so it cannot be used to reconstruct a live daily counter either.
• The only signal available today is the 429 error itself, after the limit is already hit.

Proposal

Add free-model quota fields to GET /api/v1/key, for example:

"free_tier": {
  "requests_today": 174,
  "daily_limit": 1000,
  "minute_remaining": 12,
  "minute_limit": 20
}

Alternatively (or additionally), allow /api/v1/activity to return the current, partial UTC day so clients can aggregate it themselves.

Use case

Usage-monitoring tools (menu-bar quota trackers, CI dashboards, agent orchestrators) could surface "x/1000 free requests today" next to credit balance. Individual users on free models could pace their work instead of being surprised by a 429 in the middle of a coding session. Happy to provide more detail if useful.