# Event schema

> Every event the SDKs send, field by field, with types, limits and an example of each, and the rules the engine applies to them.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/reference/event-schema/

This page is the event contract in a form you can read. It is for anyone who wants to know exactly what leaves an app, and for anyone who writes their own client. It is the same for the open-source engine and for Sypnia Cloud: the SDKs are MIT and identical for both.

It is generated from `spec/events.schema.json` in the docs repository, a JSON Schema (2020-12). When this page and the schema disagree, the schema is right. The SDKs build these events for you; see [Browser](https://docs.sypnia.com/sdks/browser), [Node](https://docs.sypnia.com/sdks/node) and [Next.js](https://docs.sypnia.com/sdks/nextjs). How a batch is sent, authenticated and answered is in the [API reference](https://docs.sypnia.com/api/ingest).

## The rules

| Rule           | What it says                                                                                                                                                                                                                                                                                                                              |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Version        | `v` is the version of this contract. It is 1. Inside version 1 fields and event types are only added, never renamed or removed. An event without `v` is read as version 1.                                                                                                                                                                |
| Unknown fields | A field this schema does not list is kept as it was sent and stored with the event. It is never a reason to reject an event. A newer SDK never breaks an older engine.                                                                                                                                                                    |
| Unknown types  | An event whose `type` this schema does not list is stored with the raw events and ignored by the parts of the engine that do not know it. It is never rejected.                                                                                                                                                                           |
| Long strings   | A string longer than its limit is cut to the limit. It is never a reason to reject an event. The SDKs cut to the same limits before sending.                                                                                                                                                                                              |
| Wrong values   | A listed field with the wrong type, or a value outside its list of allowed values, is removed from the event (set to null when the field allows null). The event is kept.                                                                                                                                                                 |
| Dropped events | An event is dropped only when a field marked as required for its type is missing or unusable (for example no `type`, a `ts` that is not a positive number, a browser event without `sid`, a vital outside its plausible range). Dropped events are counted in the answer of the ingest, with the reason. The rest of the batch is stored. |
| Stamped fields | `prj`, `rcv` and `bid` are written by the engine when the event arrives. Whatever the sender puts there is replaced. `env` is `production` when the sender leaves it out.                                                                                                                                                                 |
| Privacy        | No event carries a typed value, a request or response body, a cookie, a header, a query string or a URL hash. `url` is a path. Replay content travels apart from events, already masked in the browser.                                                                                                                                   |

## The batch

The body of POST /v1/ingest/events. The ingest key travels outside the body: in the `Authorization: Bearer spk_…` header, or in the `key` query parameter when the browser sends with `navigator.sendBeacon`, which cannot set headers. The body may be gzipped.

| Field      | Type          | Limit     | Required | Meaning                                                                                                                                         |
| ---------- | ------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_id` | string        | 64 chars  |          | An id the sender chooses for this batch, a UUID. A retry reuses it: a batch that arrives twice is stored once.                                  |
| `sent_at`  | string        |           |          | When the batch left, by the sender's clock, ISO 8601 in UTC. The engine compares it with its own clock to notice a device whose clock is wrong. |
| `sdk`      | object        |           |          | Which SDK built the batch.                                                                                                                      |
| `events`   | list of event | 200 items | yes      | The events, in the order they happened. At most 200. An empty list is accepted and stores nothing.                                              |

| Field         | Type   | Limit    | Meaning                                          |
| ------------- | ------ | -------- | ------------------------------------------------ |
| `sdk.name`    | string | 40 chars | The package name, for example `@sypnia/browser`. |
| `sdk.version` | string | 20 chars | The package version, for example `1.0.0`.        |

```json
{
  "batch_id": "0b9f6c3e-2a41-4d7e-9c1b-6f2e8a4d7c10",
  "sent_at": "2026-03-12T10:31:48Z",
  "sdk": {
    "name": "@sypnia/browser",
    "version": "1.0.0"
  },
  "events": [
    {
      "v": 1,
      "type": "click",
      "ts": 1773311503000,
      "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
      "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
      "env": "production",
      "ver": "4f2a91c",
      "person": {
        "id": "u_1042"
      },
      "account": null,
      "url": "/checkout",
      "route": "/checkout",
      "dev": "desktop",
      "vw": 1440,
      "vh": 900,
      "lang": "en",
      "sel": "#pay-button",
      "tag": "button",
      "txt": "Pay $64.00",
      "crole": "button",
      "ctx": "Your order",
      "href": null,
      "x": 912,
      "y": 640,
      "rx": 0.633,
      "ry": 640,
      "ex": 820,
      "ey": 618,
      "ew": 184,
      "eh": 44
    }
  ]
}
```

## Event types

### From the browser SDK

| Type                              | Event                           | What it is                                                                                                                       |
| --------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [`session_start`](#session_start) | Session start                   | A session began in this browser.                                                                                                 |
| [`identify`](#identify)           | Identify                        | The app said who the person is. This is the only event that carries a name or an e-mail. Every other event carries only the ids. |
| [`page_view`](#page_view)         | Page view                       | A page was shown.                                                                                                                |
| [`page_leave`](#page_leave)       | Page leave                      | The person left a page, or stopped looking at it.                                                                                |
| [`click`](#click)                 | Click                           | The person clicked something.                                                                                                    |
| [`rage_click`](#rage_click)       | Rage click                      | The person clicked the same spot again and again.                                                                                |
| [`dead_click`](#dead_click)       | Dead click                      | The person clicked something that should respond, and nothing happened.                                                          |
| [`vital`](#vital)                 | Vital (performance measurement) | One Web Vital of a page, with the element behind it.                                                                             |
| [`request`](#request)             | Request                         | The page called an API. Never the request or response body.                                                                      |
| [`error`](#error)                 | Error                           | An error in the page.                                                                                                            |
| [`custom`](#custom)               | Custom event                    | Something the app chose to report.                                                                                               |
| [`form_invalid`](#form_invalid)   | Form-validation failure         | The browser blocked a form. Never what was typed.                                                                                |
| [`replay_chunk`](#replay_chunk)   | Replay chunk marker             | A piece of the replay was uploaded. This marker is how a session's timeline knows it has a replay, and where.                    |
| [`replay_gap`](#replay_gap)       | Replay gap marker               | The replay has a hole here. The player shows it instead of pretending nothing happened.                                          |
| [`page_snapshot`](#page_snapshot) | Page snapshot marker            | A snapshot of this route was taken. The snapshot itself travels apart, to POST /v1/ingest/snapshot.                              |

### From the server SDKs

| Type                                | Event          | What it is                                                                                                |
| ----------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------- |
| [`server_request`](#server_request) | Server request | One request your server received, with the calls it made. It is the root of the server's part of a trace. |
| [`server_error`](#server_error)     | Server error   | A failure on the server.                                                                                  |

## Fields of every event

### Fields of every event

Carried by every event, from the browser and from the server.

| Field     | Type                              | Limit      | Required | Meaning                                                                                                                                                                                                                                                            |
| --------- | --------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `v`       | integer                           | always `1` |          | Version of this contract. Always 1. Read as 1 when missing.                                                                                                                                                                                                        |
| `type`    | string                            | 40 chars   | yes      | Which event this is. See the list of types.                                                                                                                                                                                                                        |
| `ts`      | number                            | > 0        | yes      | When it happened: milliseconds since 1970-01-01 UTC, by the sender's clock.                                                                                                                                                                                        |
| `env`     | string                            | 40 chars   |          | The environment, as the app set it in `init`. `production` when missing.                                                                                                                                                                                           |
| `ver`     | string or null                    | 40 chars   |          | The release: the version of the app that sent the event, as set in `init`. Use the short git commit. Null or missing when the app reports none.                                                                                                                    |
| `person`  | [PersonRef](#personref) or null   |            |          | Who the event belongs to: the id given to `identify()`. Null or missing for an anonymous event. Only `identify` events carry the name and e-mail.                                                                                                                  |
| `account` | [AccountRef](#accountref) or null |            |          | The account the person belongs to in the monitored app (a team, a company, a club): the id given to `identify()`. Null or missing when the app sends none.                                                                                                         |
| `prj`     | string                            |            |          | The project id (`prj_…`). Written by the engine from the ingest key. A value sent by the app is replaced.                                                                                                                                                          |
| `rcv`     | number                            |            |          | When the engine received the event: milliseconds since 1970-01-01 UTC, by the engine's clock. A value sent by the app is replaced.                                                                                                                                 |
| `bid`     | string                            | 64 chars   |          | The id of the batch the event arrived in: the batch's `batch_id`, or a hash of the batch's body when the sender gave none. Written by the engine on every stored event. It is how a batch that arrives twice is counted once. A value sent by the app is replaced. |

### Fields of every browser event

Carried by every event the browser SDK sends, on top of the fields of every event.

| Field   | Type           | Limit                         | Required | Meaning                                                                                                                                                                                                                                                         |
| ------- | -------------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sid`   | string         | exactly 32 hex chars          | yes      | Session id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (`localStorage`, key `sypnia:session`). A new one after 30 minutes without activity, or when another person is identified.               |
| `did`   | string         | exactly 32 hex chars          |          | Device id: 32 random hex characters the SDK keeps in the browser's storage (`localStorage`, key `sypnia:device`). It tells devices apart across sessions. It identifies nobody.                                                                                 |
| `url`   | string         | 500 chars                     |          | The page's path. Never the origin, the query or the hash.                                                                                                                                                                                                       |
| `route` | string         | 500 chars                     |          | The path with ids replaced by `:id`, so `/orders/8841` and `/orders/8842` are one route. A segment becomes `:id` when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains `%`. |
| `dev`   | string         | `mobile`, `tablet`, `desktop` |          | Device class by viewport width: `mobile` under 768 px, `tablet` under 1,024 px, otherwise `desktop`.                                                                                                                                                            |
| `vw`    | number         |                               |          | Viewport width in CSS pixels.                                                                                                                                                                                                                                   |
| `vh`    | number         |                               |          | Viewport height in CSS pixels.                                                                                                                                                                                                                                  |
| `lang`  | string or null | 16 chars                      |          | The page's language: the `lang` attribute of `<html>`, else the browser's language.                                                                                                                                                                             |

### Fields of every server event

Carried by every event the server SDKs send, on top of the fields of every event. A server event has no device, viewport or page.

| Field     | Type           | Limit                | Required | Meaning                                                                                                                                                                                                                                                         |
| --------- | -------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `service` | string         | 80 chars             |          | The name of the service that sent the event, as set in `init`, for example `shop-api`.                                                                                                                                                                          |
| `tid`     | string or null | exactly 32 hex chars |          | The trace the event belongs to. Taken from the incoming `traceparent` header, or created by the SDK.                                                                                                                                                            |
| `sid`     | string or null | exactly 32 hex chars |          | The browser session that made the request, from the `x-sypnia-session` header. Null when the request did not come from a browser session.                                                                                                                       |
| `method`  | string         | 10 chars             |          | HTTP method of the incoming request, upper case.                                                                                                                                                                                                                |
| `path`    | string         | 500 chars            |          | Path of the incoming request. Never the query.                                                                                                                                                                                                                  |
| `route`   | string         | 500 chars            |          | The path with ids replaced by `:id`, so `/orders/8841` and `/orders/8842` are one route. A segment becomes `:id` when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains `%`. |

## `session_start`

**Session start.** A session began in this browser.

**Sent:** Once for each session id a page uses: on the first event of a new session, after 30 minutes without activity, when another tab started a new session, or when another person is identified. It is queued before the event that caused it.

Its own fields, on top of the common ones:

| Field | Type           | Limit     | Required | Meaning                                                                                                        |
| ----- | -------------- | --------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `ua`  | string         | 500 chars |          | The browser's user agent string. The engine reads browser and operating system from it.                        |
| `ref` | string or null | 500 chars |          | Where the person came from: origin and path of the referrer. Never its query or hash. Null when there is none. |
| `sw`  | number         |           |          | Screen width in CSS pixels.                                                                                    |
| `sh`  | number         |           |          | Screen height in CSS pixels.                                                                                   |
| `tz`  | string         | 64 chars  |          | The browser's time zone, as an IANA name.                                                                      |

**Example**

```json
{
  "v": 1,
  "type": "session_start",
  "ts": 1773311476000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": null,
  "account": null,
  "url": "/cart",
  "route": "/cart",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
  "ref": "https://www.google.com/",
  "sw": 1728,
  "sh": 1117,
  "tz": "Europe/Madrid"
}
```

## `identify`

**Identify.** The app said who the person is. This is the only event that carries a name or an e-mail. Every other event carries only the ids.

**Sent:** When the app calls `identify()` with a person, and once more at the start of each later session of that person. Not sent when the same person and account were already sent in this session with the same name and e-mail.

Its own fields, on top of the common ones:

| Field     | Type                        | Limit | Required | Meaning                                                                                                                              |
| --------- | --------------------------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `person`  | [Person](#person)           |       | yes      | A person as the app described them in `identify()`. Name and e-mail are personal data: they are stored only when the app sends them. |
| `account` | [Account](#account) or null |       |          | The account the person belongs to, with its name if the app sent one.                                                                |

**Example**

```json
{
  "v": 1,
  "type": "identify",
  "ts": 1773311481000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "url": "/cart",
  "route": "/cart",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "person": {
    "id": "u_1042",
    "name": "Ada Park",
    "email": "ada@example.com"
  },
  "account": {
    "id": "acc_77",
    "name": "Corner Café"
  }
}
```

## `page_view`

**Page view.** A page was shown.

**Sent:** When a page loads and each time the app navigates to another path. A change of query or hash alone is not a page view.

Its own fields, on top of the common ones:

| Field  | Type           | Limit                                 | Required | Meaning                                                                                                                                                |
| ------ | -------------- | ------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `nav`  | string         | `load`, `push`, `replace`, `traverse` |          | How the person got here: `load` a full page load, `push` a navigation inside the app, `replace` a redirect inside the app, `traverse` back or forward. |
| `from` | string or null | 500 chars                             |          | The route of the page before. Null on a full page load.                                                                                                |

**Example**

```json
{
  "v": 1,
  "type": "page_view",
  "ts": 1773311488000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "nav": "push",
  "from": "/cart"
}
```

## `page_leave`

**Page leave.** The person left a page, or stopped looking at it.

**Sent:** When the app navigates away, the tab is hidden, or the page is closed. A page that is hidden and shown again can send several.

Its own fields, on top of the common ones:

| Field    | Type   | Limit | Required | Meaning                                                                                                             |
| -------- | ------ | ----- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `dur`    | number |       |          | Milliseconds on the page since it was shown, or since the tab became visible again.                                 |
| `scroll` | number | 0–100 |          | How far down the person scrolled, as a percentage of the page's height. 100 when the whole page fits on the screen. |

**Example**

```json
{
  "v": 1,
  "type": "page_leave",
  "ts": 1773311518000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "dur": 30000,
  "scroll": 100
}
```

## `click`

**Click.** The person clicked something.

**Sent:** On every click in the page. A click that a `<label>` passes on to its field counts once.

Its own fields, on top of the common ones:

| Field   | Type           | Limit                                                                                                                                                                   | Required | Meaning                                                                                                                                                                                                                        |
| ------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `sel`   | string         | 200 chars                                                                                                                                                               |          | A CSS selector for the clicked control: at most 5 levels, stopping at a `data-testid` or a stable `id`. Never contains text.                                                                                                   |
| `tag`   | string         | 20 chars                                                                                                                                                                |          | The control's tag name, lower case.                                                                                                                                                                                            |
| `txt`   | string or null | 80 chars                                                                                                                                                                |          | The control's readable name: its accessible name, its label or its visible text. For a field, the label or the placeholder, never the value. Null when there is none, when the element is masked, or when `maskAllText` is on. |
| `crole` | string         | `button`, `link`, `tab`, `menuitem`, `option`, `checkbox`, `radio`, `switch`, `select`, `input`, `textarea`, `row`, `cell`, `heading`, `image`, `icon`, `text`, `other` |          | What kind of thing was clicked, as a person would name it. Missing when unknown.                                                                                                                                               |
| `ctx`   | string or null | 80 chars                                                                                                                                                                |          | Where the control is: the title of the open dialog or menu, else the nearest heading before it. Null when there is none or when text is masked.                                                                                |
| `href`  | string or null | 500 chars                                                                                                                                                               |          | For a link, the route it points to. Null for other controls and for `mailto:`, `tel:` and non-http links.                                                                                                                      |
| `x`     | number         |                                                                                                                                                                         |          | Click position from the left of the page, in pixels.                                                                                                                                                                           |
| `y`     | number         |                                                                                                                                                                         |          | Click position from the top of the page, in pixels.                                                                                                                                                                            |
| `rx`    | number         | 0–1                                                                                                                                                                     |          | Click position from the left, as a fraction of the viewport width. Used by click maps.                                                                                                                                         |
| `ry`    | number         |                                                                                                                                                                         |          | Click position from the top of the page, in pixels. Used by click maps.                                                                                                                                                        |
| `ex`    | number         |                                                                                                                                                                         |          | Left edge of the clicked control, in page pixels.                                                                                                                                                                              |
| `ey`    | number         |                                                                                                                                                                         |          | Top edge of the clicked control, in page pixels.                                                                                                                                                                               |
| `ew`    | number         |                                                                                                                                                                         |          | Width of the clicked control, in pixels.                                                                                                                                                                                       |
| `eh`    | number         |                                                                                                                                                                         |          | Height of the clicked control, in pixels.                                                                                                                                                                                      |

**Example**

```json
{
  "v": 1,
  "type": "click",
  "ts": 1773311503000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "sel": "#pay-button",
  "tag": "button",
  "txt": "Pay $64.00",
  "crole": "button",
  "ctx": "Your order",
  "href": null,
  "x": 912,
  "y": 640,
  "rx": 0.633,
  "ry": 640,
  "ex": 820,
  "ey": 618,
  "ew": 184,
  "eh": 44
}
```

## `rage_click`

**Rage click.** The person clicked the same spot again and again.

**Sent:** Detected in the browser: 3 or more clicks within 30 px of the first, each at most 1,000 ms after the one before. Sent once, when the burst ends. Not for text fields, and not when the clicks selected text. It also starts the upload of the session's replay.

Its own fields, on top of the common ones:

Every field of [`click`](#click), plus:

| Field | Type    | Limit | Required | Meaning                                                                  |
| ----- | ------- | ----- | -------- | ------------------------------------------------------------------------ |
| `n`   | integer | min 3 | yes      | How many clicks the burst had. The other fields describe the last click. |

**Example**

```json
{
  "v": 1,
  "type": "rage_click",
  "ts": 1773311506000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "sel": "#pay-button",
  "tag": "button",
  "txt": "Pay $64.00",
  "crole": "button",
  "ctx": "Your order",
  "href": null,
  "x": 915,
  "y": 642,
  "rx": 0.635,
  "ry": 642,
  "ex": 820,
  "ey": 618,
  "ew": 184,
  "eh": 44,
  "n": 5
}
```

## `dead_click`

**Dead click.** The person clicked something that should respond, and nothing happened.

**Sent:** Detected in the browser: a click on something that looks clickable, after which nothing happened for 1,000 ms: no change in the page, no request, no navigation, no scroll, no dialog, download or new tab. The same control again within 2,000 ms counts once. It also starts the upload of the session's replay.

Its own fields, on top of the common ones:

Every field of [`click`](#click), plus:

| Field | Type    | Limit         | Required | Meaning                                                                                              |
| ----- | ------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------- |
| `n`   | integer | always `1000` | yes      | How long the SDK waited for a response before calling the click dead, in milliseconds. Always 1,000. |

**Example**

```json
{
  "v": 1,
  "type": "dead_click",
  "ts": 1773311503000,
  "sid": "5b1d9e3f7a2c4e6081b3d5f7a9c1e3b5",
  "did": "9c4e2a6f8b0d1e3f5a7c9b1d3e5f7a90",
  "env": "production",
  "ver": "4f2a91c",
  "person": null,
  "account": null,
  "url": "/checkout",
  "route": "/checkout",
  "dev": "mobile",
  "vw": 390,
  "vh": 844,
  "lang": "en",
  "sel": "#pay-button",
  "tag": "button",
  "txt": "Pay $64.00",
  "crole": "button",
  "ctx": "Your order",
  "href": null,
  "x": 195,
  "y": 1210,
  "rx": 0.5,
  "ry": 1210,
  "ex": 16,
  "ey": 1188,
  "ew": 358,
  "eh": 48,
  "n": 1000
}
```

## `vital`

**Vital (performance measurement).** One Web Vital of a page, with the element behind it.

**Sent:** LCP, FCP and TTFB once for the page that was loaded. INP and CLS once per page, when the person leaves it. A value that is not a finite number, is negative, or is above the plausible maximum (LCP, FCP, TTFB 120,000 ms; INP 60,000 ms; CLS 10) is not sent.

Its own fields, on top of the common ones:

| Field    | Type   | Limit                                  | Required | Meaning                                                                                                                                                                                                    |
| -------- | ------ | -------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | string | `LCP`, `INP`, `CLS`, `TTFB`, `FCP`     | yes      | Which vital. FCP is stored with the raw events; the Performance views show LCP, INP, CLS and TTFB.                                                                                                         |
| `value`  | number |                                        | yes      | The value: milliseconds, rounded, for LCP, INP, TTFB and FCP. A score without unit, to 4 decimals, for CLS.                                                                                                |
| `rating` | string | `good`, `needs-improvement`, `poor`    |          | The rating by the Web Vitals thresholds: LCP 2,500 and 4,000 ms; INP 200 and 500 ms; CLS 0.1 and 0.25; TTFB 800 and 1,800 ms; FCP 1,800 and 3,000 ms.                                                      |
| `sel`    | string | 200 chars                              |          | The element behind the value, as a CSS selector: the largest element painted (LCP), the element the person interacted with (INP), the element that moved most (CLS). Never text. Missing for TTFB and FCP. |
| `kind`   | string | `image`, `text`, `pointer`, `keyboard` |          | For LCP, whether the element is an `image` or `text`. For INP, whether the interaction was `pointer` or `keyboard`. Missing otherwise.                                                                     |

**Example**

```json
{
  "v": 1,
  "type": "vital",
  "ts": 1773311489240,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "name": "LCP",
  "value": 1240,
  "rating": "good",
  "sel": "#order-summary",
  "kind": "text"
}
```

## `request`

**Request.** The page called an API. Never the request or response body.

**Sent:** When a `fetch` or `XMLHttpRequest` call from the page to your own origin, or to an address listed in `traceTargets` or `recordTargets`, gets an answer or fails. Not when the tab was hidden or the session idle as the call began, and not for a call your code aborted. A call that gets no answer is recorded 1,500 ms later with status 0, unless the page was being closed.

Its own fields, on top of the common ones:

| Field    | Type           | Limit                | Required | Meaning                                                                                                                                                                            |
| -------- | -------------- | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `method` | string         | 10 chars             | yes      | HTTP method, upper case.                                                                                                                                                           |
| `host`   | string or null | 255 chars            |          | The host that was called, when it is not the page's own. Null or missing for calls to the page's own origin.                                                                       |
| `path`   | string         | 500 chars            | yes      | The route that was called: the path with ids replaced by `:id`. Never the query.                                                                                                   |
| `status` | integer        | 0–599                | yes      | HTTP status of the answer. 0 when there was no answer.                                                                                                                             |
| `dur`    | number         |                      |          | Milliseconds from the call to the answer. `ts` is when the call began.                                                                                                             |
| `tid`    | string         | exactly 32 hex chars |          | Trace id: 32 lowercase hex characters, a W3C trace id. Never all zeros.                                                                                                            |
| `code`   | string         | 40 chars             |          | Only for status 400 and above: the error code from a JSON answer (`code`, `error_code`, or `error` when it looks like a code).                                                     |
| `msg`    | string         | 160 chars            |          | Only for status 400 and above: the start of the error message from a JSON answer (`error`, else `message`), with white space collapsed and e-mail addresses replaced by `[email]`. |

**Example**

```json
{
  "v": 1,
  "type": "request",
  "ts": 1773311503100,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "method": "POST",
  "host": null,
  "path": "/api/checkout",
  "status": 400,
  "dur": 412,
  "tid": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
  "code": "amount_required",
  "msg": "The payment has no amount."
}
```

## `error`

**Error.** An error in the page.

**Sent:** When an error reaches the window uncaught, a promise is rejected with no handler, or the app calls `reportError()`. Not sent: errors of browser extensions and of scripts from other origins, `Script error.` without detail, the `ResizeObserver loop` notice, the same fingerprint again within 5,000 ms, and more than 20 errors in 60 seconds. It also starts the upload of the session's replay.

Its own fields, on top of the common ones:

| Field    | Type           | Limit                                     | Required | Meaning                                                                                                                                                                                                         |
| -------- | -------------- | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | string         | 100 chars                                 | yes      | The error's name, for example `TypeError`. `UnhandledRejection` when a promise was rejected with something that is not an Error.                                                                                |
| `msg`    | string         | 500 chars                                 | yes      | The error's message, with e-mail addresses replaced by `[email]`.                                                                                                                                               |
| `stack`  | string or null | 4000 chars                                |          | The stack as the browser wrote it, not parsed, with e-mail addresses replaced by `[email]`. Null when the browser gave none. The engine translates it with the release's source maps.                           |
| `digest` | string or null | 100 chars                                 |          | An id the framework gave the error, when there is one (Next.js gives a digest to errors thrown on the server). Null otherwise.                                                                                  |
| `src`    | string         | `window`, `promise`, `boundary`, `manual` |          | How the SDK learned of it: `window` an uncaught error, `promise` an unhandled rejection, `boundary` an error boundary of the framework, `manual` a call to `reportError()`.                                     |
| `fp`     | string         | exactly 16 hex chars                      |          | The fingerprint: 16 hex characters computed by the SDK from the name, the message with its variable parts removed, and the first frame of the app's own code. Errors with the same fingerprint are one problem. |

**Example**

```json
{
  "v": 1,
  "type": "error",
  "ts": 1773311507000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "name": "ApiError",
  "msg": "POST /api/checkout failed with 400 (amount_required)",
  "stack": "ApiError: POST /api/checkout failed with 400 (amount_required)\n    at o (https://shop.example/assets/checkout-3f9c.js:1:48211)\n    at async HTMLButtonElement.<anonymous> (https://shop.example/assets/checkout-3f9c.js:1:49002)",
  "digest": null,
  "src": "promise",
  "fp": "1522805793228d19"
}
```

## `custom`

**Custom event.** Something the app chose to report.

**Sent:** When the app calls `track(name, props)`.

Its own fields, on top of the common ones:

| Field   | Type   | Limit    | Required | Meaning                                                                                                                                                                              |
| ------- | ------ | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`  | string | 80 chars | yes      | The event's name, chosen by the app.                                                                                                                                                 |
| `props` | object | 20 keys  |          | Up to 20 properties. A name has at most 40 characters. A value is a string of at most 200 characters, a finite number, a boolean or null. Anything else (objects, lists) is removed. |

**Example**

```json
{
  "v": 1,
  "type": "custom",
  "ts": 1773311495000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "name": "coupon_applied",
  "props": {
    "code": "SPRING10",
    "discount_cents": 640,
    "first_order": false
  }
}
```

## `form_invalid`

**Form-validation failure.** The browser blocked a form. Never what was typed.

**Sent:** When the browser refuses to submit a form because a field is not valid (the native `invalid` event). At most one per 1,000 ms.

Its own fields, on top of the common ones:

| Field    | Type           | Limit                                                                                                                                                  | Required | Meaning                                                                                         |
| -------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------- |
| `field`  | string or null | 80 chars                                                                                                                                               |          | The field's readable name: its label or placeholder. Never its value. Null when text is masked. |
| `ctx`    | string or null | 80 chars                                                                                                                                               |          | Where the field is: the dialog's title or the nearest heading. Null when text is masked.        |
| `reason` | string or null | `valueMissing`, `typeMismatch`, `patternMismatch`, `tooShort`, `tooLong`, `rangeUnderflow`, `rangeOverflow`, `stepMismatch`, `badInput`, `customError` |          | Why the browser refused the field: the first true key of its `ValidityState`.                   |
| `sel`    | string         | 200 chars                                                                                                                                              |          | A CSS selector for the field.                                                                   |

**Example**

```json
{
  "v": 1,
  "type": "form_invalid",
  "ts": 1773311499000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "field": "Postal code",
  "ctx": "Shipping address",
  "reason": "patternMismatch",
  "sel": "#postal-code"
}
```

## `replay_chunk`

**Replay chunk marker.** A piece of the replay was uploaded. This marker is how a session's timeline knows it has a replay, and where.

**Sent:** After the engine accepted one piece of the session's recording. The recording itself travels apart, to POST /v1/ingest/replay.

Its own fields, on top of the common ones:

| Field   | Type    | Limit | Required | Meaning                                                                                                                                                                                                |
| ------- | ------- | ----- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `seq`   | integer | 0–719 | yes      | The piece's number in the session, from 0.                                                                                                                                                             |
| `bytes` | integer |       |          | The piece's size before compression, in characters of JSON.                                                                                                                                            |
| `mask`  | integer | 1–9   |          | Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 `maskAllText` (also every text of the page). |
| `full`  | boolean |       |          | True when the piece holds a full copy of the page, so the player can start from it.                                                                                                                    |

**Example**

```json
{
  "v": 1,
  "type": "replay_chunk",
  "ts": 1773311507400,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "seq": 0,
  "bytes": 148220,
  "mask": 1,
  "full": true
}
```

## `replay_gap`

**Replay gap marker.** The replay has a hole here. The player shows it instead of pretending nothing happened.

**Sent:** When a piece of the recording is lost for good.

Its own fields, on top of the common ones:

| Field    | Type    | Limit                                     | Required | Meaning                                                                                                                                                                                                                                            |
| -------- | ------- | ----------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `seq`    | integer | 0–719                                     | yes      | The number of the piece that is missing.                                                                                                                                                                                                           |
| `reason` | string  | `rejected`, `failed`, `overflow`, `limit` | yes      | Why: `rejected` the engine refused the piece, `failed` every retry failed, `overflow` too much was waiting in memory and the oldest piece was let go, `limit` the project reached its replays limit and the engine told the SDK to stop recording. |
| `mask`   | integer | 1–9                                       |          | Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 `maskAllText` (also every text of the page).                                             |

**Example**

```json
{
  "v": 1,
  "type": "replay_gap",
  "ts": 1773311530000,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "seq": 3,
  "reason": "failed",
  "mask": 1
}
```

## `page_snapshot`

**Page snapshot marker.** A snapshot of this route was taken. The snapshot itself travels apart, to POST /v1/ingest/snapshot.

**Sent:** When a page snapshot (the picture behind a click map) was uploaded, or could not be.

Its own fields, on top of the common ones:

| Field     | Type    | Limit                               | Required | Meaning                                                                                                                                                                                                |
| --------- | ------- | ----------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bytes`   | integer |                                     |          | The snapshot's size before compression, in characters of JSON.                                                                                                                                         |
| `mask`    | integer | 1–9                                 |          | Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 `maskAllText` (also every text of the page). |
| `skipped` | string  | `too_big`, `upload_failed`, `limit` |          | Present when the snapshot was not stored: `too_big` above 3,000,000 characters, `upload_failed` the upload failed (it is not retried), `limit` the project reached a limit.                            |

**Example**

```json
{
  "v": 1,
  "type": "page_snapshot",
  "ts": 1773311490600,
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "did": "3e7a1c9d5b2f4a8e6c0d9b7f1a3e5c2d",
  "env": "production",
  "ver": "4f2a91c",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "url": "/checkout",
  "route": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "lang": "en",
  "bytes": 412880,
  "mask": 1
}
```

## `server_request`

**Server request.** One request your server received, with the calls it made. It is the root of the server's part of a trace.

**Sent:** Once for every request the server handled, when the answer has been sent. A request still running after 20,000 ms is sent at that moment as a partial record; the full record replaces it if the request finishes.

Its own fields, on top of the common ones:

| Field      | Type                  | Limit                | Required | Meaning                                                                                                                                 |
| ---------- | --------------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `tid`      | string                | exactly 32 hex chars | yes      | Trace id: 32 lowercase hex characters, a W3C trace id. Never all zeros.                                                                 |
| `span`     | string                | exactly 16 hex chars |          | Span id: 16 lowercase hex characters, a W3C span id.                                                                                    |
| `parent`   | string or null        | exactly 16 hex chars |          | The span id from the incoming `traceparent` header: the browser's call, or the calling service's span. Null when the trace starts here. |
| `status`   | integer or null       | 100–599              |          | The HTTP status that was sent. Null when unknown, as in a partial record.                                                               |
| `dur`      | number                |                      |          | Milliseconds from receiving the request to the end of the answer.                                                                       |
| `spans`    | list of [Span](#span) | 200 items            |          | The calls the request made, in the order they began. At most 200 are kept.                                                              |
| `span_n`   | integer               |                      |          | How many spans the request had, counting those beyond 200.                                                                              |
| `span_err` | integer               |                      |          | How many of them failed.                                                                                                                |
| `db_n`     | integer               |                      |          | How many database calls (`kind` `db`) the request made.                                                                                 |
| `db_ms`    | number                |                      |          | Milliseconds spent in database calls, added up.                                                                                         |
| `err`      | string or null        | 500 chars            |          | The message of the error that failed the request, when it threw. Null otherwise.                                                        |
| `fp`       | string or null        | exactly 16 hex chars |          | The fingerprint of that error, or of the timeout in a partial record. Null otherwise.                                                   |
| `cold`     | boolean               |                      |          | True for the first request of a new process (a cold start on serverless).                                                               |
| `partial`  | boolean               |                      |          | True only for the record written while the request was still running.                                                                   |
| `msg`      | string                | 500 chars            |          | Partial records only: how long the request had been running and the three longest calls still in flight.                                |

**Example**

```json
{
  "v": 1,
  "type": "server_request",
  "ts": 1773311503130,
  "service": "shop-api",
  "env": "production",
  "ver": "4f2a91c",
  "tid": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
  "span": "a1b2c3d4e5f60718",
  "parent": "0f1e2d3c4b5a6978",
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "method": "POST",
  "path": "/api/checkout",
  "route": "/api/checkout",
  "status": 400,
  "dur": 398.2,
  "spans": [
    {
      "id": "1a2b3c4d5e6f7081",
      "parent": null,
      "name": "SELECT carts",
      "kind": "db",
      "start": 6.1,
      "dur": 18,
      "status": "ok",
      "code": null,
      "attrs": {
        "db.system.name": "postgresql",
        "db.collection.name": "carts",
        "db.operation.name": "SELECT"
      }
    },
    {
      "id": "2b3c4d5e6f708192",
      "parent": null,
      "name": "SELECT cart_items",
      "kind": "db",
      "start": 25.3,
      "dur": 22.1,
      "status": "ok",
      "code": null,
      "attrs": {
        "db.system.name": "postgresql",
        "db.collection.name": "cart_items",
        "db.operation.name": "SELECT"
      }
    },
    {
      "id": "3c4d5e6f708192a3",
      "parent": null,
      "name": "POST /v1/payments",
      "kind": "http",
      "start": 49,
      "dur": 340.2,
      "status": "error",
      "code": "400",
      "attrs": {
        "http.request.method": "POST",
        "server.address": "payments.internal",
        "url.path": "/v1/payments",
        "http.response.status_code": 400
      }
    }
  ],
  "span_n": 3,
  "span_err": 1,
  "db_n": 2,
  "db_ms": 40.1,
  "err": null,
  "fp": null,
  "cold": false,
  "partial": false
}
```

## `server_error`

**Server error.** A failure on the server.

**Sent:** When an error is thrown and not caught while handling a request, when a call the request made fails, when a request answers 500 or above with no other failure, when the code writes to `console.error` during a request, or when the app calls `reportError()`. At most 5 per request, 3 of them from `console.error`, one per fingerprint.

Its own fields, on top of the common ones:

| Field    | Type           | Limit                                         | Required | Meaning                                                                                                                                                                                                                                                                                                                      |
| -------- | -------------- | --------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`   | string         | 100 chars                                     | yes      | The error's name. For a failed call, the kind and its code, for example `HTTP 400` or `DB 23505`. For a 5xx answer with no other failure, `HTTP 500`.                                                                                                                                                                        |
| `msg`    | string         | 500 chars                                     | yes      | The message. For a failed call it is redacted before it leaves the server: e-mail addresses, URLs, UUIDs, quoted values, long tokens and every run of digits are replaced, and it is followed by the call and the route, for example `duplicate key value violates unique constraint (INSERT orders) in POST /api/checkout`. |
| `stack`  | string or null | 4000 chars                                    |          | The stack, when there is an Error behind it. Null otherwise.                                                                                                                                                                                                                                                                 |
| `digest` | string or null | 100 chars                                     |          | An id the framework gave the error, when there is one. The browser's `error` for the same failure carries the same digest.                                                                                                                                                                                                   |
| `src`    | string         | `uncaught`, `span`, `status`, `log`, `manual` |          | How the SDK learned of it: `uncaught` an error nobody caught, `span` a call that failed, `status` an answer of 500 or above with no other failure, `log` a `console.error` during a request, `manual` a call to `reportError()`.                                                                                             |
| `span`   | string or null | exactly 16 hex chars                          |          | For `src` `span`, the id of the span that failed.                                                                                                                                                                                                                                                                            |
| `fp`     | string         | exactly 16 hex chars                          |          | The fingerprint: 16 hex characters. Failures with the same fingerprint are one problem.                                                                                                                                                                                                                                      |

**Example**

```json
{
  "v": 1,
  "type": "server_error",
  "ts": 1773311503519,
  "service": "shop-api",
  "env": "production",
  "ver": "4f2a91c",
  "tid": "7c2e9a4b1d8f4e6a9b3c5d7e1f2a4b6c",
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "person": {
    "id": "u_1042"
  },
  "account": {
    "id": "acc_77"
  },
  "method": "POST",
  "path": "/api/checkout",
  "route": "/api/checkout",
  "name": "HTTP 400",
  "msg": "amount is required (POST /v1/payments) in POST /api/checkout",
  "stack": null,
  "digest": null,
  "src": "span",
  "span": "3c4d5e6f708192a3",
  "fp": "88a44b15205cb153"
}
```

## Shared shapes

### Person

A person as the app described them in `identify()`. Name and e-mail are personal data: they are stored only when the app sends them.

| Field   | Type           | Limit     | Required | Meaning                                                 |
| ------- | -------------- | --------- | -------- | ------------------------------------------------------- |
| `id`    | string         | 128 chars | yes      | The person's id in the monitored app. An opaque string. |
| `name`  | string or null | 120 chars |          | The person's name. Optional. Personal data.             |
| `email` | string or null | 254 chars |          | The person's e-mail address. Optional. Personal data.   |

### Account

The account a person belongs to in the monitored app, as the app described it in `identify()`.

| Field  | Type           | Limit     | Required | Meaning                                                  |
| ------ | -------------- | --------- | -------- | -------------------------------------------------------- |
| `id`   | string         | 128 chars | yes      | The account's id in the monitored app. An opaque string. |
| `name` | string or null | 120 chars |          | The account's name. Optional.                            |

### PersonRef

Person (reference)

| Field | Type   | Limit     | Required | Meaning                                                                             |
| ----- | ------ | --------- | -------- | ----------------------------------------------------------------------------------- |
| `id`  | string | 128 chars | yes      | The person's id in the monitored app. An opaque string: Sypnia never interprets it. |

### AccountRef

Account (reference)

| Field | Type   | Limit     | Required | Meaning                                                  |
| ----- | ------ | --------- | -------- | -------------------------------------------------------- |
| `id`  | string | 128 chars | yes      | The account's id in the monitored app. An opaque string. |

### Span

One step inside a server request: a database call, a call to another service, or an internal step. The shape is compatible with OpenTelemetry.

| Field    | Type           | Limit                    | Required | Meaning                                                                                                                                                                                                                                                                                                  |
| -------- | -------------- | ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`     | string         | exactly 16 hex chars     | yes      | Span id: 16 lowercase hex characters, a W3C span id.                                                                                                                                                                                                                                                     |
| `parent` | string or null | exactly 16 hex chars     |          | The span that caused this one. Null when the request itself did.                                                                                                                                                                                                                                         |
| `name`   | string         | 120 chars                | yes      | What the step is: `SELECT carts`, `POST /v1/payments`. Never a full SQL statement, never a query string.                                                                                                                                                                                                 |
| `kind`   | string         | `db`, `http`, `internal` | yes      | `db` a database call, `http` a call to another service, `internal` anything else.                                                                                                                                                                                                                        |
| `start`  | number         |                          | yes      | Milliseconds from the start of the request (`ts`) to the start of the span, to 0.1 ms.                                                                                                                                                                                                                   |
| `dur`    | number         |                          | yes      | How long the span took, in milliseconds, to 0.1 ms. For a span still running in a partial record, how long it had been running.                                                                                                                                                                          |
| `status` | string         | `ok`, `error`            |          | `error` when the call got no answer, answered 400, answered 500 or above, or threw. Other answers, such as 401, 404 or 409, are `ok`.                                                                                                                                                                    |
| `code`   | string or null | 40 chars                 |          | The HTTP status or the database's error code, as text. `0` when there was no answer. Null when there is none.                                                                                                                                                                                            |
| `attrs`  | object         | 64 keys                  |          | Up to 64 details, named as OpenTelemetry names them (`http.request.method`, `server.address`, `db.system.name`…). A value is a string of at most 256 characters, a number or a boolean. Attributes whose name contains `authorization`, `cookie`, `password`, `secret` or `token` are removed at ingest. |
| `run`    | boolean        |                          |          | True when the span was still running as the record was written. Only in partial records.                                                                                                                                                                                                                 |

### MaskPolicy

Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 `maskAllText` (also every text of the page).

## Replay and snapshot uploads

These two bodies are not events. They travel to their own endpoints and are counted as replays.

### ReplayChunk

The body of POST /v1/ingest/replay: one piece of a session's recording. Not an event. The engine stores `events` as sent and never looks inside: masking happens in the browser.

| Field      | Type           | Limit                | Required | Meaning                                                                                                                                                                                                                                                         |
| ---------- | -------------- | -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sid`      | string         | exactly 32 hex chars | yes      | Session id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (`localStorage`, key `sypnia:session`). A new one after 30 minutes without activity, or when another person is identified.               |
| `seq`      | integer        | 0–719                | yes      | The piece's number in the session, from 0. Sending the same number again replaces the piece.                                                                                                                                                                    |
| `ts_start` | number         |                      |          | Time of the first recorded change in the piece, in milliseconds since 1970-01-01 UTC.                                                                                                                                                                           |
| `ts_end`   | number         |                      |          | Time of the last recorded change in the piece.                                                                                                                                                                                                                  |
| `route`    | string         | 500 chars            |          | The path with ids replaced by `:id`, so `/orders/8841` and `/orders/8842` are one route. A segment becomes `:id` when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains `%`. |
| `url`      | string         | 500 chars            |          | The page's path when the piece was opened.                                                                                                                                                                                                                      |
| `vw`       | number         |                      |          | Viewport width when the piece was opened.                                                                                                                                                                                                                       |
| `vh`       | number         |                      |          | Viewport height when the piece was opened.                                                                                                                                                                                                                      |
| `full`     | boolean        |                      |          | True when the piece holds a full copy of the page.                                                                                                                                                                                                              |
| `mask`     | integer        | 1–9                  |          | Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 `maskAllText` (also every text of the page).                                                          |
| `events`   | list of object |                      | yes      | The recorded changes, in the recorder's own format (rrweb events). Opaque to the engine.                                                                                                                                                                        |

```json
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "seq": 3,
  "ts_start": 1773311497000,
  "ts_end": 1773311507000,
  "route": "/checkout",
  "url": "/checkout",
  "vw": 1440,
  "vh": 900,
  "full": false,
  "mask": 1,
  "events": [
    {
      "type": 3,
      "timestamp": 1773311503000,
      "data": {
        "source": 2,
        "type": 2,
        "id": 418,
        "x": 912,
        "y": 640
      }
    }
  ]
}
```

### PageSnapshot

The body of POST /v1/ingest/snapshot: one page as it looked, with the same masking as a replay. Click maps are drawn over it. Not an event.

| Field      | Type    | Limit                         | Required | Meaning                                                                                                                                                                                                                                                         |
| ---------- | ------- | ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sid`      | string  | exactly 32 hex chars          | yes      | Session id: 32 random lowercase hex characters, created by the browser SDK and shared by every tab of the same browser (`localStorage`, key `sypnia:session`). A new one after 30 minutes without activity, or when another person is identified.               |
| `route`    | string  | 500 chars                     | yes      | The path with ids replaced by `:id`, so `/orders/8841` and `/orders/8842` are one route. A segment becomes `:id` when it is all digits, a UUID, a hex string of 16 characters or more, a token of 20 characters or more that contains a digit, or contains `%`. |
| `url`      | string  | 500 chars                     |          | The page's path.                                                                                                                                                                                                                                                |
| `dev`      | string  | `mobile`, `tablet`, `desktop` |          | Device class of the browser that took it.                                                                                                                                                                                                                       |
| `vw`       | number  |                               |          | Viewport width.                                                                                                                                                                                                                                                 |
| `vh`       | number  |                               |          | Viewport height.                                                                                                                                                                                                                                                |
| `ph`       | number  |                               |          | Full height of the page, in pixels.                                                                                                                                                                                                                             |
| `ts`       | number  |                               |          | When it was taken, in milliseconds since 1970-01-01 UTC.                                                                                                                                                                                                        |
| `mask`     | integer | 1–9                           |          | Which masking rules the SDK applied before sending: 1 the default (everything typed is masked, page text as shown, marked elements masked or left out), 2 `maskAllText` (also every text of the page).                                                          |
| `snapshot` | object  |                               | yes      | The page's tree, in the recorder's own format (an rrweb snapshot). Opaque to the engine.                                                                                                                                                                        |

```json
{
  "sid": "8f3a6c1e9b2d4f07a5c3e1b8d6f4a2c0",
  "route": "/checkout",
  "url": "/checkout",
  "dev": "desktop",
  "vw": 1440,
  "vh": 900,
  "ph": 1630,
  "ts": 1773311490000,
  "mask": 1,
  "snapshot": {
    "type": 0,
    "childNodes": [],
    "id": 1
  }
}
```

## Limits and constants

The numbers the SDKs and the engine use. They are part of the contract: the code implements these values.

| Area       | Constant                           | Value                                              |
| ---------- | ---------------------------------- | -------------------------------------------------- |
| `batch`    | `events_per_batch`                 | 200                                                |
| `batch`    | `browser_batch_chars`              | 40,800                                             |
| `batch`    | `body_bytes_after_decompression`   | 2,097,152                                          |
| `batch`    | `flush_interval_ms`                | 10,000                                             |
| `batch`    | `flush_at_events`                  | 50                                                 |
| `batch`    | `queue_max_events`                 | 500                                                |
| `batch`    | `gzip_above_chars`                 | 2048                                               |
| `batch`    | `retry_delays_ms`                  | 1000, 4000, 15,000                                 |
| `session`  | `idle_ms`                          | 1,800,000                                          |
| `session`  | `id_length_hex`                    | 32                                                 |
| `errors`   | `per_minute`                       | 20                                                 |
| `errors`   | `dedupe_ms`                        | 5000                                               |
| `clicks`   | `rage_window_ms`                   | 1000                                               |
| `clicks`   | `rage_radius_px`                   | 30                                                 |
| `clicks`   | `rage_min_clicks`                  | 3                                                  |
| `clicks`   | `dead_wait_ms`                     | 1000                                               |
| `clicks`   | `dead_dedupe_ms`                   | 2000                                               |
| `forms`    | `invalid_dedupe_ms`                | 1000                                               |
| `requests` | `unanswered_grace_ms`              | 1500                                               |
| `vitals`   | `max_ms`                           | LCP 120,000, FCP 120,000, TTFB 120,000, INP 60,000 |
| `vitals`   | `max_cls`                          | 10                                                 |
| `replay`   | `chunk_interval_ms`                | 10,000                                             |
| `replay`   | `chunk_chars`                      | 200,000                                            |
| `replay`   | `buffer_ms`                        | 30,000                                             |
| `replay`   | `max_chunks_per_session`           | 720                                                |
| `replay`   | `upload_bytes_after_decompression` | 4,000,000                                          |
| `replay`   | `snapshots_per_session`            | 5                                                  |
| `replay`   | `snapshot_chars`                   | 3,000,000                                          |
| `server`   | `spans_per_request`                | 200                                                |
| `server`   | `span_attributes`                  | 64                                                 |
| `server`   | `span_attribute_chars`             | 256                                                |
| `server`   | `failures_per_request`             | 5                                                  |
| `server`   | `log_failures_per_request`         | 3                                                  |
| `server`   | `slow_request_ms`                  | 20,000                                             |
