---
title: Quotas Reference
path: reference/quotas
status: published
---

Quota configuration and usage tracking across the partner / tenant / user / group / share hierarchy.

**Base path:** `/api/v1/quotas/`

## Quota object

```json
{
  "id": "qta_01J7A",
  "tenant_id": "tnt_01J3A",
  "target_type": "user",
  "target_id": "usr_01J4M",
  "limit_bytes": 53687091200,
  "limit_type": "hard",
  "warning_threshold_1": 70,
  "warning_threshold_2": 85,
  "warning_threshold_3": 95,
  "grace_period_days": 7,
  "grace_extra_percent": 10,
  "grace_started_at": null,
  "exempt": false,
  "exempt_reason": null
}
```

**target_type:** `tenant`, `partner`, `user`, `group`, `share`.
**limit_type:** `hard` (writes blocked at limit) or `soft` (writes allowed during grace window).

## Usage object

```json
{
  "target_type": "user",
  "target_id": "usr_01J4M",
  "used_bytes": 42301234567,
  "file_count": 8200,
  "folder_count": 412,
  "version_bytes": 5120000000,
  "trash_bytes": 840000000,
  "calculated_at": "2026-04-23T10:00:00Z"
}
```

## Tenant quota

### GET /api/v1/quotas/tenant

Caller's tenant quota.

### PUT /api/v1/quotas/tenant

Set tenant quota.

**Requires:** `partner:admin` or higher.

**Body:** `limit_bytes`, `limit_type`, `warning_threshold_1/2/3`, `grace_period_days`, `grace_extra_percent`.

## Partner quotas

Superuser only (`*`).

### GET /api/v1/quotas/partner

Caller's partner quota.

### PUT /api/v1/quotas/partner

Set caller's partner quota.

### GET /api/v1/quotas/partners/{partner_id}

### PUT /api/v1/quotas/partners/{partner_id}

## Specific-tenant quotas

### GET /api/v1/quotas/tenants/{tenant_id}

### PUT /api/v1/quotas/tenants/{tenant_id}

Require `partner:admin` for tenants under the caller's partner.

## User quotas

### GET /api/v1/quotas/users

List all user quotas in tenant.

**Query:** `limit` (1–1000), `offset`.

### GET /api/v1/quotas/users/{user_id}

Single user's quota.

### PUT /api/v1/quotas/users/{user_id}

Set quota.

**Body:** all quota fields.

### DELETE /api/v1/quotas/users/{user_id}

Remove user quota (falls back to tenant-level). Returns 204.

### POST /api/v1/quotas/users/{user_id}/exempt

Set exemption.

**Body:** `{"exempt": true, "reason": "CEO"}`.

## Group quotas

### GET /api/v1/quotas/groups

### GET /api/v1/quotas/groups/{group_id}

### PUT /api/v1/quotas/groups/{group_id}

### DELETE /api/v1/quotas/groups/{group_id}

### POST /api/v1/quotas/groups/{group_id}/exempt

Same shape as user quotas.

## Share quotas

### GET /api/v1/quotas/shares/{share_id}

### PUT /api/v1/quotas/shares/{share_id}

## Usage

### GET /api/v1/quotas/usage/tenant

Tenant-wide usage.

**Query:** `recalculate` (force re-compute from scratch; expensive).

### GET /api/v1/quotas/usage/users

Usage for all users in tenant.

### GET /api/v1/quotas/usage/users/{user_id}

One user's usage.

### GET /api/v1/quotas/usage/groups

### GET /api/v1/quotas/usage/groups/{group_id}

### GET /api/v1/quotas/usage/shares

### GET /api/v1/quotas/usage/shares/{share_id}

### GET /api/v1/quotas/usage/history

Historical usage time series.

**Query:**

| Param | Notes |
|-------|-------|
| `target_type` | `tenant`, `user`, `group`, `share` |
| `target_id` | |
| `days` | 1–365, default 30 |

**Response:** `{history: [{date, used_bytes, file_count}, ...]}`.

## Enforcement behavior

For **hard** quotas, writes that would exceed the limit fail with `507 QUOTA_EXCEEDED`. The error identifies which quota triggered.

For **soft** quotas, the first write above the limit starts the grace window (`grace_started_at` set). Writes succeed up to `limit_bytes * (1 + grace_extra_percent/100)` for `grace_period_days`, then start failing. Once usage drops below the limit, the grace window clears.

Warning thresholds don't block writes — they trigger notification events.

## Hierarchy

A write must satisfy every applicable quota:

- The share's quota
- The owning user's quota
- Every group the user is in (group quotas)
- The tenant quota
- The partner quota (if set)

The most restrictive quota wins. The error response names the level that failed.

## Error codes

| Code | HTTP | When |
|------|------|------|
| `QUOTA_EXCEEDED` | 507 | Any applicable quota would be exceeded |
| `QUOTA_GRACE_EXHAUSTED` | 507 | Soft-quota grace window expired |

## Related

- [Multi-tenancy](/docs/scaidrive/core-concepts/multi-tenancy)
- [Shares and Ownership](/docs/scaidrive/core-concepts/shares-and-ownership)