---
title: "Current test-result usage for the organization."
method: GET
path: "/api/v1/usage"
tags: ["Auth"]
---

# Current test-result usage for the organization.

`GET /api/v1/usage`

## Request

- Base URL: `https://platform.buildpulse.io`
- URL: `https://platform.buildpulse.io/api/v1/usage`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

Returns the calling organization's test-result usage for the
current UTC calendar month, measured against its plan limit.

This is the read-only entitlement contract consumed by the
web-client and the MCP server. It is **always open** — it is
never subject to overage read-enforcement and never returns
`402`, so a restricted organization can still discover why its
data reads are gated.

`status` is the staged-overage stage (the same derivation every
surface uses — derived from the canonical fields the ingestion
lambda stamps on the organization):
- `within` — under the limit, or not on an enforced plan
  (legacy / free / unlimited orgs always report `within`).
- `notify` — over the limit, days 0–2 (or in trial): full data
  access plus a banner. Not restricted.
- `soft` — over the limit, days 3–13: data-read endpoints return
  `402 plan_limit_exceeded`. Ingestion is unaffected.
- `hard` — over the limit, day 14+: data-read endpoints return
  `402` AND ingestion is paused (raw retained ~30 days).

Only `soft` and `hard` gate reads; `within` and `notify` keep full
access. `limit` is `0` for organizations with no enforced monthly
limit.

## Response `200`

Current usage snapshot.

- object
  - `usage` integer, required: Test results recorded this UTC month.
  - `limit` integer, required: Monthly test-result limit (0 = unlimited / not enforced).
  - `status` 'within' | 'notify' | 'soft' | 'hard', required
  - `periodStart` string, date-time, required: Start of the current UTC calendar month (RFC3339).

## Other responses

- `401`: Missing, malformed, or invalid token; or — for legacy 40-hex tokens only — the organization has no active plan (`marketplacePurchases.unitCount > 0`). The new `bp_<64-hex>` path has no plan gate, so a 401 there means the token shape was wrong, the hash didn't match, or the token has expired. Response body is empty (matches legacy Rails).

---

[API](https://skmtc.dev/buildpulse/apis/buildpulse-platform-api.md) · [All operations](https://skmtc.dev/buildpulse/apis/buildpulse-platform-api/llms.txt) · [OpenAPI document](https://skmtc.dev/buildpulse/apis/buildpulse-platform-api/revisions/2e68b4b2df6a?raw)