---
title: "Your own usage vs quota (FREE — any tier)"
method: GET
path: "/usage"
---

# Your own usage vs quota (FREE — any tier)

`GET /usage`

## Request

- Base URL: `https://api.livetennisapi.com/api/public/v1`
- URL: `https://api.livetennisapi.com/api/public/v1/usage`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Durable daily usage for the calling key: tier, limits, today's calls (current to the second) and a 30-day history. The per-minute window is on the X-RateLimit-* headers of every response, not here. Calls to this endpoint are quota-exempt — checking your usage never consumes it.

## Response `200`

Usage summary

- Usage
  - `principal` string: Opaque ref to your own key
  - `tier` 'free' | 'basic' | 'pro' | 'ultra'
  - `base_tier` string: Subscription tier; equals `tier` unless a temporary grant is active
  - `tier_expires_at` string, date-time, nullable: When a temporary tier grant reverts, else null
  - `channel` string
  - `limits` object
    - `per_minute` integer, nullable
    - `per_day` integer, nullable
  - `today` object
    - `calls` integer
    - `errors` integer
    - `remaining_day` integer, nullable: Requests still SERVABLE today: the day allowance less SERVED calls (`calls - errors`). Refused requests never spend the allowance, so this does not fall when a `429`, `403` or `404` is returned. Null when the tier carries no day cap.
  - `history` object[]: Last 30 days, oldest first
    - `day` string, date
    - `calls` integer
    - `errors` integer
  - `as_of` string, date-time

## Other responses

- `401`: Missing, unknown, or disabled credentials
- `429`: Rate limit exceeded (Retry-After header present). Three body shapes, told apart by `error` and `scope`: the per-MINUTE limit (`rate_limited`, with `upgrade_url`, `tier` and `price` naming the next tier up); the per-DAY quota (`rate_limited` with `scope: "day"`, `limit_per_day`, and `resets_at` — the absolute ISO instant the daily window resets); and `abuse_throttled` with `retry_at_epoch` — a 24-hour block applied to clients that keep hammering far past their cap, which a well-behaved retry loop never sees. Fix the loop rather than retrying through it.

---

[API](https://skmtc.dev/livetennisapi/apis/live-tennis-api.md) · [All operations](https://skmtc.dev/livetennisapi/apis/live-tennis-api/llms.txt) · [OpenAPI document](https://skmtc.dev/livetennisapi/apis/live-tennis-api/revisions/7881947e8e43?raw)