---
title: "Open a bounded compaction headroom grant"
method: POST
path: "/vaults/v1/{vault_id}/compaction-grant"
tags: ["vault"]
---

# Open a bounded compaction headroom grant

`POST /vaults/v1/{vault_id}/compaction-grant`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/vaults/v1/{vault_id}/compaction-grant`
- Auth: one of:
  - API key in header `SIGN-IN-WITH-X`
  - HTTP bearer
  - HTTP bearer

vault-checkpoint-cadence (design D3/D4). A compaction transiently needs roughly 2x a vault's source_bytes — the new checkpoint must land durably before the superseded history is pruned — which the org-pooled quota otherwise refuses for a vault already near its limit. Opens a bounded, TTL'd (~1 hour, hard-coded) grant that raises the org's EFFECTIVE storage limit by exactly `granted_bytes` while active — never the reported usage. The server measures and caps `granted_bytes` at the vault's OWN current billed source_bytes; `requested_bytes`, if given, can only narrow it, never widen it. At most one active grant per project (a partial unique index enforces it); a second open while one is active refuses `409 VAULT_COMPACTION_GRANT_ACTIVE`. An expired-but-unswept grant releases its slot on this SAME call rather than waiting on the hourly sweep. Granted bytes are never billed and can never become standing storage.

## Path parameters

- `vault_id` string, required

## Headers

- `SIGN-IN-WITH-X` string, required

## Request body

- object
  - `requested_bytes` number: Optional client-requested cap. The server never grants MORE than the vault's own measured billed source_bytes regardless of this value.

## Response `201`

Grant opened

- object
  - `granted_bytes` string: Decimal byte count as a string (values exceed 2^53).
  - `expires_at` string, date-time
  - `pool_used_bytes` string: Decimal byte count as a string (values exceed 2^53).
  - `pool_limit_bytes` string: Decimal byte count as a string (values exceed 2^53) — the bare tier limit, unaffected by the grant.
  - `effective_pool_limit_bytes` string: Decimal byte count as a string (values exceed 2^53) — pool_limit_bytes plus every currently active compaction-grant headroom on the org, including this one.

## Other responses

- `403`: Not authorized (VAULT_ACCESS_DENIED)
- `409`: VAULT_COMPACTION_GRANT_ACTIVE — an active grant already exists on this project

---

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