---
title: "Read audit retention usage"
method: GET
path: "/v1/audit/usage"
tags: ["Organizations"]
---

# Read audit retention usage

`GET /v1/audit/usage`

Organization administrator access to currently captured, retained audit history only; this is not coverage of every cloud action. Requires the latest literal metadata.capabilities.auditLogs=true and deployment visibility; feature disable returns 403 audit_feature_disabled without deleting history or changing capture preference. Legacy arbitrary payloads are preserved separately and are not backfilled or returned. One operation may contain multiple child events. Visibility is independent of capture entitlement. No duration, charge or continuous-drain guarantee is made. Reads stored policy and tenant counters, plus the oldest retained operation. Capture requires audit entitlement, organization captureOn and the deployment capture flag. A ready organization without a policy is lazily initialized ON, including on this GET, with one system lifecycle event. Temporary defaults: 6,000,000 retained OPERATIONS (not child events), 300-second grouping window, change/security/execution/access/request/lifecycle categories, cloud/delete_oldest for Enterprise or operator/keep_all for explicit self-hosted entitlement. Existing OFF and custom policies are preserved. These are provisional declarations, not enforced caps: no billing, cleanup or deletion is activated. Drains are not configured. Logical bytes are not physical database size; access capture may itself add one operation.

## Response `200`

Current stored audit policy and usage, without a history scan.

- object
  - `entitlement` object, required
    - `enabled` boolean, required
    - `source` 'enterprise_plan' | 'self_hosted' | 'none', required
  - `captureOn` boolean, required
  - `captureAvailable` boolean, required
  - `policy` object, nullable, required
    - `organizationId` string, required
    - `revision` integer, required
    - `source` 'cloud' | 'operator', required
    - `enabled` boolean, required
    - `categories` string[], required
    - `allowance` integer, required
    - `excessMode` 'delete_oldest' | 'paid_overage' | 'keep_all', required
    - `effectiveAt` string, date-time, required
    - `captureStartedAt` string, date-time, nullable, required
    - `attachmentWindowSeconds` integer, required
  - `captureEnabled` boolean, required
  - `retainedOperations` integer, required
  - `eventCount` integer, required
  - `logicalBytes` integer, required
  - `oldestAvailableAt` string, date-time, nullable, required
  - `measuredAt` string, date-time, nullable, required
  - `billing` 'disabled', required
  - `cleanup` 'dry_run', required
  - `drains` 'not_configured', required

## Other responses

- `400` — Malformed query, cursor, mismatched filters, operation scope or export format.
- `401` — Authentication required.
- `403` — Organization administrator permission, audit feature and visibility required.
- `404` — Organization or retained operation not found, including foreign-tenant targets.
- `410` — Cursor expired or retained snapshot anchors/history are no longer available.
- `503` — Audit storage or required access capture unavailable; no audit content is released.

## Changes

- **2026-09-30** `0d10fe7f6aa1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/audit/usage/get.md)

---

[API](https://skmtc.dev/openworklabs/apis/den-api.md) · [All operations](https://skmtc.dev/openworklabs/apis/den-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openworklabs/apis/den-api/revisions/406852f37cc0?raw)