---
title: "Read many heads' exact stored bytes in one call"
method: POST
path: "/vaults/v1/{vault_id}/head-reads"
tags: ["vault"]
---

# Read many heads' exact stored bytes in one call

`POST /vaults/v1/{vault_id}/head-reads`

## Request

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

The batched sibling of `GET /vaults/v1/{vault_id}/heads/{generation}`. Heads are generation-addressed and therefore cannot ride the carrier-only `object-reads` batch, so a cold chain walk otherwise pays one round trip per generation for bytes that are ~1.2 KB each; one POST carries a whole listing page. `stored_bytes` is base64url of the EXACT stored bytes — byte-identical to the per-generation route, and the same encoding the composite state read's `head.stored_bytes` uses. **All-or-nothing:** any requested generation with no stored head refuses the WHOLE batch with `RESOURCE_NOT_FOUND` naming the first absent one in request order; no partial page is ever served. Nothing here is server-verified or re-serialized — hash what was served, exactly as on every other stored-bytes read. Never lifecycle-gated.

## Path parameters

- `vault_id` string, required

## Headers

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

## Request body

- object
  - `generations` string[], required: 1 to 1000 generations, STRICTLY ASCENDING. Anything else refuses `VALIDATION_FAILED` before any storage read.

## Response `200`

Each requested head's exact stored bytes, in request order

- object
  - `format` string
  - `repo_id` string
  - `heads` object[]
    - `generation` string: 16 lowercase hex.
    - `stored_bytes` string: base64url of the exact stored bytes.
    - `stored_bytes_sha256` string: SHA-256 of those bytes, hex.

## Other responses

- `400`: Empty, over 1000, non-hex16, or not strictly ascending (VALIDATION_FAILED)
- `403`: Not authorized (VAULT_ACCESS_DENIED)
- `404`: A requested generation has no stored head; the whole batch is refused naming it (RESOURCE_NOT_FOUND)

---

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