> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /metadata: Server-Blind Usage and Quota Aggregates

> Retrieve server-visible usage aggregates — envelope counts, byte totals, sync quota, device count, and last sync timestamp — with zero plaintext exposure.

<style>
  {`
      main, article, .prose {
        margin-left: 2.5cm !important;
        margin-right: 2.5cm !important;
      }
      `}
</style>

The `GET /metadata` endpoint returns a structured snapshot of everything the server can observe about your agent — and nothing more. In keeping with sovseal's zero-knowledge design, the response contains only counts, byte totals, and timestamps derived from Layer A (server-visible) metadata. No ciphertext payloads, no decrypted content, and no key material is ever included. Use this endpoint to monitor quota consumption, track active device sync counts, and feed observability dashboards without compromising memory privacy.

<Note>
  All metrics in this response are derived from Layer A server-observable metadata only. The server never decrypts envelopes or inspects memory contents to compute these values.
</Note>

## Request

```http theme={null}
GET /metadata
Authorization: Bearer <TOKEN>
```

This endpoint takes no query parameters. The agent is resolved from the bearer token.

## Response

### 200 OK

<ResponseField name="envelopeCount" type="integer">
  Exact count of encrypted envelopes currently stored in the replication log for this agent.
</ResponseField>

<ResponseField name="totalBytes" type="integer">
  Cumulative byte size of all stored ciphertext blocks across the entire replication history.
</ResponseField>

<ResponseField name="storeOps" type="integer">
  Total count of write (store) operations the client has performed against this agent.
</ResponseField>

<ResponseField name="recallRequests" type="integer">
  Best-effort count of client semantic query (recall) operations. Note that 0-RTT queries execute entirely locally and are not directly observable by the server — this counter reflects only network-routed recall traffic.
</ResponseField>

<ResponseField name="syncOpsUsed" type="integer">
  Total sync operations consumed in the current billing cycle.
</ResponseField>

<ResponseField name="syncOpsQuota" type="integer">
  Total sync operations permitted in the current billing cycle. Compare against `syncOpsUsed` to gauge remaining capacity.
</ResponseField>

<ResponseField name="devicesInSync" type="integer">
  Number of active devices currently linked to this agent key and participating in replication.
</ResponseField>

<ResponseField name="avgLatencyMs" type="number">
  Average network sync latency in milliseconds. Returns `0` for client-side local queries that do not transit the network.
</ResponseField>

<ResponseField name="lastSyncAt" type="string">
  RFC 3339 timestamp of the last confirmed replication synchronization event.
</ResponseField>

### Example Response

```json theme={null}
{
  "envelopeCount": 142,
  "totalBytes": 1048576,
  "storeOps": 142,
  "recallRequests": 890,
  "syncOpsUsed": 142,
  "syncOpsQuota": 1000,
  "devicesInSync": 2,
  "avgLatencyMs": 0,
  "lastSyncAt": "2026-06-09T16:45:30.123Z"
}
```

## curl Example

```bash theme={null}
curl -G https://ksrlmubaxzwufziwarps.supabase.co/functions/v1/v2-agent-state/metadata \
  -H "Authorization: Bearer sov_live_YOUR_KEY"
```