---
title: "Current-period usage vs plan limits"
method: GET
path: "/api/v1/usage"
tags: ["Repository"]
---

# Current-period usage vs plan limits

`GET /api/v1/usage`

## Request

- Base URL: `https://dungbeetle.dev`
- URL: `https://dungbeetle.dev/api/v1/usage`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Metering only — limits are not enforced here. Requires the `analytics:read` scope on agent tokens.

## Response `200`

Usage for the team that owns this repository.

- UsageReport
  - `period` string, required: Billing period as 'YYYY-MM' (UTC).
  - `plan` 'free' | 'starter' | 'team' | 'business' | 'enterprise', required
  - `metered` boolean, required: False in self-host mode (usage tracked, never enforced).
  - `snapshots` integer, required
  - `storageBytes` integer, required
  - `repos` integer, required
  - `limits` object, required: Per-dimension plan limits; null means unlimited.
    - `repos` integer, nullable, required
    - `storageBytes` integer, nullable, required
    - `snapshotsPerPeriod` integer, nullable, required
    - `retentionDays` integer, nullable, required
  - `warnings` object[], required
    - `dimension` 'repos' | 'storage' | 'snapshots', required
    - `used` integer, required
    - `limit` integer, required
    - `status` 'warning' | 'over', required
    - `hard` boolean, required

## Other responses

- `401`: Missing/malformed Authorization header (`code: unauthorized`), bad Basic credentials (`code: invalid_credentials`), or an invalid, expired, or revoked agent token (`code: invalid_agent_token`).
- `403`: Agent token outside its granted scopes (`code: missing_scope`, with a `scope` field naming the required scope) or a route that is not agent-accessible at all (`code: agent_forbidden`). Basic-auth requests never see this.
- `429`: Too many failed attempts or uploads from this client (`code: rate_limited`). Honor the `Retry-After` header; successful authenticated requests never count toward the limit.

---

[API](https://skmtc.dev/dungbeetle/apis/dungbeetle-cloud-api.md) · [All operations](https://skmtc.dev/dungbeetle/apis/dungbeetle-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/dungbeetle/apis/dungbeetle-cloud-api/revisions/74778b90420a?raw)