Usage Statistics

#Use it when

• You need account-level usage numbers in your app
• You want to warn users before they hit plan limits
• You are building your own lightweight usage dashboard
• You want to show a "resets in X seconds" countdown to your users

#Code examples

1curl https://api.navy/v1/usage \
2  -H "Authorization: Bearer sk-navy-YOUR_KEY"

#Response shape

1{
2  "plan": "free",
3  "limits": {
4    "tokens_per_day": 250000,
5    "rpm": 30
6  },
7  "usage": {
8    "tokens_used_today": 18420,
9    "tokens_remaining_today": 231580,
10    "percent_used": 7.4,
11    "resets_at_utc": "2025-01-01T00:00:00.000Z",
12    "resets_in_ms": 41523000
13  },
14  "rate_limits": {
15    "per_minute": {
16      "limit": 30,
17      "used": 4,
18      "remaining": 26,
19      "resets_in_ms": 38120
20    }
21  },
22  "server_time_utc": "2024-12-31T12:25:17.000Z"
23}

#Response fields

• plan — Your current plan tier
• limits.tokens_per_day — Daily token allowance for your plan
• limits.rpm — Requests per minute allowance for your plan
• usage.tokens_used_today — Tokens consumed since the last UTC midnight reset (after multipliers)
• usage.tokens_remaining_today — Tokens you can still spend today
• usage.percent_used — Daily quota used, to one decimal place
• usage.resets_at_utc / usage.resets_in_ms — When the daily quota next resets (always 00:00 UTC)
• rate_limits.per_minute — Current sliding-window RPM state
• server_time_utc — Server clock, useful for syncing your countdowns

#Notes

• Daily quotas reset at 00:00 UTC, not on your local timezone
• Per-minute counters use a sliding 60-second window from the first request in the window
• Cache usage responses briefly instead of hammering the endpoint
• Pair usage with GET /v1/models if you want to explain why some models cost more (each model has a token_multiplier)