> ## 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.

# POST /telemetry

> Submit opt-in aggregate-only usage telemetry.

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

This endpoint accepts client-side usage statistics rollups. It enforces a strict aggregate-only whitelist to ensure no cleartext memory contents or PII can ever be sent to the database.

<Warning>
  **Session JWT Required**

  This endpoint requires a WorkOS AuthKit session JWT.
</Warning>

***

## 1. Submit Telemetry Report

Push a daily rollup of numeric counters to the platform.

```http theme={null}
POST /telemetry
```

### Request Body Schema

The request must contain **only** the following whitelist fields. Extra fields are rejected immediately to protect privacy.

| Field          | Type      | Required | Description                                                               |
| :------------- | :-------- | :------- | :------------------------------------------------------------------------ |
| `memory_count` | `integer` | No       | Current count of stored memories (must be ≥ 0).                           |
| `device_count` | `integer` | No       | Number of active syncing devices (must be ≥ 0).                           |
| `bytes_stored` | `integer` | No       | Total size of local database files in bytes (must be ≥ 0).                |
| `sync_ops`     | `integer` | No       | Number of synchronization actions completed in this window (must be ≥ 0). |
| `window_start` | `string`  | No       | ISO-8601 timestamp for the start of the daily rollup window.              |

### Example Request Body

```json theme={null}
{
  "memory_count": 1240,
  "device_count": 2,
  "bytes_stored": 8104820,
  "sync_ops": 420,
  "window_start": "2026-06-09T00:00:00.000Z"
}
```

***

## Processing Gates

1. **Opt-In Enforcement**: The server retrieves the user's dashboard settings. If `telemetry_opt_in` is not explicitly `true`, the write is rejected with `403 telemetry_disabled`.
2. **Strict Whitelisting**: If the request contains any keys outside the whitelist (e.g. `memory_contents`, `metadata`), it is rejected with `400 non_aggregate_field`.
3. **Postgres Upsert**: Statistics are upserted into the database. A unique constraint on `(user_id, window_start)` aggregates inputs to a single row per day.

***

## Response Schema (201 Created)

```json theme={null}
{
  "aggregate": {
    "user_id": "0x123456789...",
    "window_start": "2026-06-09T00:00:00.000Z",
    "memory_count": 1240,
    "device_count": 2,
    "bytes_stored": 8104820,
    "sync_ops": 420,
    "reported_at": "2026-06-09T16:45:30.123Z"
  }
}
```