---
title: "Read the composite pin-current state in one call"
method: GET
path: "/vaults/v1/{vault_id}/state"
tags: ["vault"]
---

# Read the composite pin-current state in one call

`GET /vaults/v1/{vault_id}/state`

## Request

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

The vault record, the newest generation, the newest head's exact stored bytes, and the ref_state/retention_roots carrier ciphertext — inlined under a 256 KiB per-carrier cap, else a presigned URL. Every byte is the stored representation, hash-addressed by the same receipts the per-object reads use; nothing here is server-derived or re-serialized, and no key-envelope material is ever returned. The client verifies the chain link, carrier hashes (against the head's own embedded receipts), and signature exactly as it does walking the paginated heads listing — a caller whose pin is more than one generation behind newest_generation ignores head/carriers here and falls back to that listing walk (unless the optional `since` delta below covers it). head/carriers are null while the vault has no ordinary admitted generation yet — both the freshly-allocated window (newest_generation null) and the genesis-only window (newest_generation equal to the genesis generation, which is a vault_genesis object and never rides head). Same auth chain as object-reads (gitvault.writer, authorize-before-reveal). Never lifecycle-gated. `Cache-Control: private, no-store`.

## Path parameters

- `vault_id` string, required

## Query parameters

- `since` string
- `restore` '1'

## Headers

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

## Response `200`

Composite state

- object
  - `vault` object: The vault record — identical shape to GET /vaults/v1/{vault_id}.
  - `newest_generation` string, nullable
  - `head` object, nullable: Null for a freshly allocated vault with no admitted generation yet.
    - `stored_bytes` string: base64url, byte-identical to the stored head object (the same bytes GET .../heads/{generation} returns).
    - `stored_bytes_sha256` string
  - `carriers` object, nullable: Null alongside head when there is no admitted generation yet. Each of ref_state/retention_roots carries EITHER `inline` (base64url ciphertext, at or under the per-carrier cap) OR `presigned_url` + `expires_at` (above the cap) OR, on a storage_profile "byo" vault, `byo_key` (its relative key under byo_destination; run402 holds no payload copy) — never more than one arm; the client verifies against the head's own embedded ciphertext_sha256. The `presigned_url` arm additionally carries `edge_url` when the platform's optional edge cache is configured — same additive, prefer-then-fall-back contract as `POST .../object-reads`'s own `edge_url` field (both kinds here are edge-eligible).
    - `ref_state` object
      - `inline` string
      - `presigned_url` string
      - `edge_url` string: Additive, optional — see POST .../object-reads's edge_url.
      - `expires_at` string, date-time
      - `byo_key` string: storage_profile "byo" vaults only: the carrier's relative key under the vault's byo_destination, in place of inline/presigned_url — read it from your own bucket.
    - `retention_roots` object
      - `inline` string
      - `presigned_url` string
      - `edge_url` string: Additive, optional — see POST .../object-reads's edge_url.
      - `expires_at` string, date-time
      - `byo_key` string: storage_profile "byo" vaults only: the carrier's relative key under the vault's byo_destination, in place of inline/presigned_url — read it from your own bucket.
  - `delta` object: vault-delta-fetch. Present ONLY when the request's `since` qualified — omitted (never null) on every disqualification, so an older gateway is indistinguishable from a disqualified span. Nothing here is server-verified or re-serialized: verify it exactly as you would the unbatched heads/head-reads/object-reads walk (chain-link each head against its predecessor, each pack's receipt hash before opening it, apply in chain order) and fall back to the paginated walk on any mismatch.
    - `since` string: Echoes the request's `since` — a chain generation, not a timestamp; see the parameter's own description above.
    - `heads` object[]: The intermediate heads' exact stored bytes, in chain order — `since` EXCLUSIVE, `newest_generation` INCLUSIVE. The same exact-stored-bytes encoding as POST .../head-reads.
      - `generation` string
      - `stored_bytes` string: base64url, byte-identical to GET .../heads/{generation}.
      - `stored_bytes_sha256` string
    - `packs` object[]: Every WAL pack the span's heads reference, flat, keyed by object_id. Inline at or under a fixed per-pack cap AND a fixed total-response inline budget (order 256 KiB / 1 MiB) — a presigned reference above either cap, degrading pack-by-pack (inline until the budget is spent, references after).
      - `object_kind` 'wal_pack'
      - `object_id` string
      - `inline` string: base64url ciphertext — present when this pack fit the inline caps.
      - `presigned_url` string: Present when this pack exceeded the inline caps, instead of `inline`.
      - `edge_url` string: Additive, optional — see POST .../object-reads's edge_url. Present only alongside presigned_url.
      - `expires_at` string, date-time
  - `restore_plan` object: vault-restore-recipe. Present ONLY when `restore=1` AND a checkpoint boundary qualified — omitted (never null) on every disqualification, so an older gateway is indistinguishable from a disqualified vault. Nothing here is server-verified or re-serialized: verify it exactly as you would the unbatched heads/head-reads/object-reads walk (backward chain-link from newest, the claim set's writer signature and its cross-field equality with the manifest, each pack's receipt hash before opening it, apply in chain order) and fall back to the backward walk on any mismatch — already-verified plan heads are cache hits there.
    - `boundary_generation` string: The newest checkpoint-bearing generation at or below `newest_generation` (16 lowercase hex), or `0000000000000000` when no checkpoint exists and the whole chain fits the bound — the genesis fallback (never itself a readable head).
    - `heads` object[]: Every head from `boundary_generation` through `newest_generation`, ascending, INCLUSIVE of both ends — the same exact-stored-bytes encoding as POST .../head-reads.
      - `generation` string
      - `stored_bytes` string: base64url, byte-identical to GET .../heads/{generation}.
      - `stored_bytes_sha256` string
    - `checkpoint` object, nullable: Null exactly when `boundary_generation` is the genesis fallback (no checkpoint exists). Both members carry the EXACT stored bytes inline, always — never routed through the shared object-reads inline budget, so a large sibling pack can never starve them.
      - `claim_set` object
        - `object_id` string
        - `stored_bytes` string: base64url — the exact stored bytes of the plaintext, writer-signed checkpoint claim set.
      - `manifest` object
        - `object_id` string
        - `stored_bytes` string: base64url — the exact stored bytes of the checkpoint manifest's ciphertext frame.
    - `packs` object[]: Every checkpoint pack the boundary's claim set names, followed by every WAL pack the span's heads reference — checkpoint packs first (claim-set order), then WAL packs (chain order), a courtesy only; the client re-derives order from its own verified data. The identical entry shape POST .../object-reads returns (inline/presigned_url/edge_url), so the same settled-fetch machinery consumes them unchanged.
      - `object_kind` 'checkpoint_pack' | 'wal_pack'
      - `object_id` string
      - `inline` string: base64url ciphertext — present when this pack fit the inline caps.
      - `presigned_url` string: Present when this pack exceeded the inline caps, instead of `inline`.
      - `edge_url` string: Additive, optional — see POST .../object-reads's edge_url. Present only alongside presigned_url.
      - `expires_at` string, date-time

## Other responses

- `403`: Not authorized (VAULT_ACCESS_DENIED)
- `409`: CHAIN_BROKEN — the newest head is malformed, or absent its ref_state/retention_roots receipt (a server-side integrity fault, not a client error)

---

[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)