---
title: "Your usage and limits, over your own API key"
method: GET
path: "/v1/usage"
---

# Your usage and limits, over your own API key

`GET /v1/usage`

## Request

- Base URL: `https://api.trackingmcp.com`
- URL: `https://api.trackingmcp.com/v1/usage`
- Auth: HTTP bearer

The counters and limits for the org the key belongs to, from the same ledgers the API enforces against and the sales console shows, so this number, your bill and your rep never disagree. Also mounted at /v1/account/usage.

## Response `200`

Per-product usage for the current calendar month.

- object
  - `ok` boolean
  - `data` object
    - `period` string: UTC calendar month these counters cover.
    - `next_expiry` string, date, nullable: Earliest valid_until across enabled products; access ends after this date.
    - `invalid_references_this_month` integer: Requests refused because YOUR reference was malformed or its carrier is unsupported. Your input errors, never billed, kept apart from consumption.
    - `products` object[]
      - `product` string
      - `channel` string
      - `plan` 'free' | 'paid'
      - `billing_mode` 'monthly' | 'per_shipment'
      - `valid_until` string, date, nullable
      - `start_date` string, date, nullable
      - `refused_this_month` integer: Requests we turned away this month (over the unique allowance, expired access, or a per-key rate cap). Never billed.
      - `last_refused_at` string, date-time, nullable
      - `calls` object: API-call traffic against your plan's call allowance. `used` is this product's calls this month (your own reads of usage/account/api-keys are excluded); `limit`/`remaining` are the call ceiling and what is left of it; `test_used` is the slice of `used` spent on a test key. Distinct from `allowance`, the unique-reference budget that actually bills.
        - `used` integer
        - `limit` integer, nullable: Calls allowed this period (your plan allowance, lowered by any per-key rate cap). Null only when neither is set.
        - `remaining` integer, nullable
        - `test_used` integer: Of `used`, the calls made on a test key. A test key spends a sandbox, never your commercial allowance.
      - `allowance` object: What you can consume, in the unit you are billed: one unique reference per period. This is the ceiling the add/lookup gate enforces.
        - `basis` 'unique_reference'
        - `limit` integer, nullable: Maximum unique references this period; null means no ceiling is set.
        - `used` integer: Unique references charged this period.
        - `remaining` integer, nullable

## Other responses

- `401`: Missing or invalid API key.

---

[API](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api.md) · [All operations](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/trackingmcp/apis/trackingmcp-rest-api/revisions/6bb8d8172ceb?raw)