API reference

Account

GET /account — stored, read, and written byte counters for your credential.

GET /account

Returns usage counters for the credential signing the request.

curl "$TESSERA_API/account?$AUTH"

Response — 200 OK

{
  "storageBytes": 62914560,
  "readBytes": 12582912,
  "writeBytes": 67108864
}

Field	Description
`storageBytes`	Currently stored bytes attributed to this credential.
`readBytes`	Cumulative bytes read.
`writeBytes`	Cumulative bytes written.

Status	Body	Cause
`401`	plain text	Signature or credential problem.
`405`	`method not allowed`	Not a `GET`.
`503`	`billing unavailable`	The metering subsystem is not available on this deployment.

Metering is not fully wired up yet

This endpoint may return zeros even after you have stored data. Byte-level metering is not yet recorded on every code path, so treat these counters as indicative and not as a billing record. Authoritative usage figures come from invoices. We would rather tell you this than let you build a dashboard on a counter that does not move.

Storage caps

When a credential has a storage cap and a write would exceed it, the write is refused with 402 Payment Required before anything is stored:

{
  "error": "storage cap exceeded",
  "capBytes": 5497558138880,
  "incomingBytes": 62914560
}

402 can come from three endpoints, and each accounts differently:

Endpoint	Charged at
`POST /prepare-write`	`totalShards × 4 MiB`
`POST /slabs`	`sectors × 4 MiB` per slab
`POST /objects`	4 KiB per object, for the metadata record

Note that accounting is in sectors, not in logical bytes, and a sector is charged whole. A 100 KiB object in its own slab is accounted at 15 sectors — 60 MiB. This is the strongest argument for packing many small objects into shared slabs; see Packing strategy.

Handling 402 in a client

Treat it as a hard stop that needs an operator, not as a retryable error:

if (res.status === 402) {
  const { capBytes, incomingBytes } = await res.json()
  // Do not retry — the answer will not change until the cap or the usage does.
  throw new QuotaExceeded({ capBytes, incomingBytes })
}

Retrying a 402 on a schedule will simply produce a 402 on a schedule. Surface it, alert on it, and raise the cap or delete something.