---
title: "Current usage and tier limits for the authenticated API key"
method: GET
path: "/v1/usage"
tags: ["usage"]
---

# Current usage and tier limits for the authenticated API key

`GET /v1/usage`

## Request

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

Returns the caller's pricing tier, per-window limits, current usage, remaining quota, billing period boundary, and entitlement flags. current_usage counters are recorded for every tier — including unlimited (enterprise) keys, whose windows are counted observationally even though no limit is enforced — so they are safe to build usage-based alerting on. `tier_limits.alert_subscriptions` / `current_usage.alert_subscriptions_count` refer to alert subscriptions managed via the /v1/alerts endpoints (POST /v1/alerts/subscriptions, GET /v1/alerts/subscriptions, DELETE /v1/alerts/subscriptions/{id}) — there is no /v1/subscriptions endpoint. Not rate-limited — safe to poll from the developer portal.

## Cookies

- `ctix_session` string, nullable

## Response `200`

Successful Response

- UsageResponse: Response shape for GET /v1/usage (and the /mcp-api/usage mirror). Fields: * ``tier`` — caller's pricing tier. * ``tier_limits`` — limits from TIER_LIMITS for this tier; ``None`` values mean unlimited. * ``current_usage`` — observed counts in the current billing windows. * ``remaining`` — ``tier_limits - current_usage`` per window; ``None`` for unlimited windows. * ``billing_period`` — current UTC month and its reset boundary. * ``firehose_enabled`` — whether the SSE firehose add-on is active. Always ``False`` until the firehose feature ships (task #20). * ``commercial_use_allowed`` — contractual redistribution gate (Scale + Enterprise tiers).
  - `tier` string, required
  - `tier_limits` object, required
  - `current_usage` UsageCurrent, required: Snapshot of the caller's current usage across all metered windows.
    - `single_host_per_hr` integer
    - `full_domain_per_hr` integer
    - `mcp_per_min` integer
    - `global_sweep_per_hr` integer
    - `monthly` integer
    - `alert_subscriptions_count` integer: Number of alert subscriptions this key has created via the /v1/alerts endpoints (POST /v1/alerts/subscriptions, GET /v1/alerts/subscriptions, DELETE /v1/alerts/subscriptions/{id}).
  - `remaining` UsageRemaining, required: Remaining quota per window. ``None`` = unlimited for that tier/window.
    - `single_host_per_hr` integer, nullable
    - `full_domain_per_hr` integer, nullable
    - `mcp_per_min` integer, nullable
    - `global_sweep_per_hr` integer, nullable
    - `monthly` integer, nullable
    - `alert_subscriptions` integer, nullable: Remaining alert-subscription slots for this tier. Alert subscriptions are managed via the /v1/alerts endpoints (POST /v1/alerts/subscriptions et al.) — there is no /v1/subscriptions endpoint. None = unlimited.
  - `billing_period` UsageBillingPeriod, required: Current billing period (UTC-aligned calendar month).
    - `period` string, required
    - `resets_at` string, date-time, required
  - `firehose_enabled` boolean
  - `commercial_use_allowed` boolean
  - `soft_overage_active` boolean
  - `hard_cap` integer, nullable
  - `user_email` string, nullable
  - `key` UsageKeyState: Lifecycle state of the authenticated API key (task #618). Surfaced in the ``key`` block of GET /v1/usage (and both MCP mirrors) so integrations can monitor their own credential health — most importantly ``expires_at``, which is set when the key was rotated with a grace period and counts down to a 403 ``expired_api_key``.
    - `id` string, uuid, required
    - `label` string, nullable
    - `is_active` boolean
    - `created_at` string, date-time, nullable
    - `last_used_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
  - `effective_depth` object, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ctindex/apis/certindex-api.md) · [All operations](https://skmtc.dev/ctindex/apis/certindex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ctindex/apis/certindex-api/revisions/d5bc0ec85bc9?raw)