---
title: "Get the workspace usage against every limit"
method: GET
path: "/v1/usage-limits"
tags: ["usage-limits"]
---

# Get the workspace usage against every limit

`GET /v1/usage-limits`

## Request

- Base URL: `https://api.patricia.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.patricia.app/v1/usage-limits`
- Auth: HTTP bearer

Every limit the caller's workspace has, with current usage where one applies: monthly spend and per-run budgets, credits, meeting-recording slots and minutes, proactive-reply caps, the bug-report filing cap, the data-retention window, and the reasoning posture. Read-only; each limit is changed on its own settings surface.

## Headers

- `X-Tenant-Id` string, nullable

## Response `200`

Successful Response

- UsageLimitsResponse: Every limit the caller's workspace has, with current usage, in display order.
  - `sections` UsageLimitSection[], required
    - `key` string, required
    - `title` string, required
    - `description` string, required
    - `items` UsageLimitItem[], required
      - `key` string, required: Stable machine id for this limit (e.g. 'spend.monthly_cap').
      - `label` string, required: Friendly name shown on the card.
      - `summary` string, required: Plain-language one-liner explaining what the limit does.
      - `kind` 'meter' | 'balance' | 'setting', required: How the item renders: meter, balance, or setting.
      - `status` 'ok' | 'near' | 'reached' | 'off', required: Honest state: ok, near (80%+), reached, or off.
      - `used` number, nullable: Current usage (meters) or remaining amount (balances).
      - `limit` number, nullable: The cap (meters) or configured value (settings).
      - `unit` 'usd' | 'credits' | 'minutes' | 'recordings' | 'replies' | 'reports' | 'days' | 'runs', nullable: How to format the numbers.
      - `period_label` string, nullable: When the numbers apply, e.g. 'this month' or 'right now'.
      - `source` 'default' | 'custom', nullable: Whether the cap is Patricia's recommended default or a workspace override.
      - `note` string, nullable: Honest context, e.g. why a feature-off limit has nothing to show.
      - `detail` string, nullable: Technical detail for the advanced reveal.
      - `manage_tab` 'billing' | 'spending' | 'data' | 'model', nullable: The Settings tab where this limit is changed, when one exists.

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden. Inspect response body `code` for the specific reason (for example: PERMISSION_DENIED, EMAIL_NOT_VERIFIED, TENANT_ACCESS_REQUIRED, ROLE_UNRESOLVED)
- `404`: Not found
- `422`: Validation error

---

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