Usage

Last verified: 2026-06-20 (Task #388 — multi-feature portal restructure).

GET /v1/usage returns the calling key's plan, environment, current-period bounds, plan limits, and current usage + remaining for every quota dimension. Calling this endpoint never burns request quota and is explicitly excluded from rate-limit enforcement — so developers can always see why they're being throttled.

Request

curl -s "https://api.travelmode.ai/v1/usage" \
  -H "Authorization: Bearer tm_weather_..."

Any valid key can read its own usage. No extra scope is required.

Response (200 OK)

{
  "data": {
    "plan": "free",
    "environment": "production",
    "is_internal": false,
    "period": {
      "start": "2026-04-01T00:00:00.000Z",
      "end":   "2026-05-01T00:00:00.000Z"
    },
    "limits": {
      "requests_per_month": 1000,
      "timeline_items_per_month": 100,
      "active_watches": 0,
      "route_calls_per_month": 0
    },
    "usage": {
      "requests":       { "limit": 1000, "used": 42, "remaining": 958 },
      "timeline_items": { "limit":  100, "used":  6, "remaining":  94 },
      "route_calls":    { "limit":    0, "used":  0, "remaining":   0 },
      "active_watches": { "limit":    0, "used":  0, "remaining":   0 }
    }
  },
  "meta": {
    "request_id": "7c0f3c2c-9e4a-4d29-b4a2-9c2b4e9f5c11",
    "generated_at": "2026-04-25T18:01:13.500Z",
    "environment": "production",
    "billing_units": 0
  }
}

Notes

• The quota dimensions themselves (what counts toward requests, timeline_items, route_calls, and active_watches) are defined by each product feature. For Weather, see the Weather rate-limits guide.
• GET /v1/usage logs billing_units = 0 and does not move the requests counter, so you can poll it as often as you want.