# Sampling and quotas

> Which sessions are recorded and how to change it, what the SDKs send and hold back, the «slow down» signal, and exactly what happens when a project reaches a limit.

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

This page is for whoever decides how much Sypnia records and what it costs. The SDKs behave the same with the open-source engine and with Sypnia Cloud. What differs is where limits come from: a plan on Sypnia Cloud, a quota you set yourself (or none) on your own engine.

**At the end you will know:** which sessions get a replay, how to record more or fewer, and what your app's SDK does when a limit is reached. Nothing is ever dropped silently.

## What is sampled, and what is not

| Signal                                                                 | Sampled? | Rule                                                                                                                                |
| ---------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Errors                                                                 | No       | Every error is sent, within the noise rules: the same error counts once per 5 seconds, and at most 20 errors a minute per page.     |
| Page views, clicks, rage and dead clicks, form failures, custom events | No       | Every one is sent.                                                                                                                  |
| Performance (LCP, INP, CLS, TTFB)                                      | No       | Every page reports its values.                                                                                                      |
| API calls from the browser                                             | No       | Every call to your origin and to `traceTargets` and `recordTargets`.                                                                |
| Server requests (Node, Next.js)                                        | No       | Every request is traced, except static files, `OPTIONS` and your `ignoreRoutes`. Sampling of successful requests is **\[Planned]**. |
| OpenTelemetry spans                                                    | By you   | Sypnia stores what your SDK or Collector sends.                                                                                     |
| **Replays**                                                            | **Yes**  | See below.                                                                                                                          |
| Page snapshots, for click maps                                         | Yes      | Half of the sessions, at most one per route and five per session.                                                                   |

## Which sessions get a replay

The engine decides once per session, and the SDK asks for the decision when the session starts. There are three ways into a recording:

1. **Something goes wrong.** Every session keeps its last 30 to 60 seconds in the browser's memory and uploads nothing. At the first error, rage click or dead click, the SDK uploads those seconds and records from there on. This needs no setting.
2. **The session is in the sampled share.** A share of all sessions is recorded from their start. The default is 10 %.
3. **An «always record» rule** names the session's person or account.

The decision is stable: the same session always gets the same answer, in every tab. If the SDK cannot reach the engine to ask, it behaves as in point 1.

A recording ends after 720 pieces, which is two hours of recording. The session goes on without it.

### Change the share

The share is a project setting, `replay.sample_rate`, from `0` to `1`. It is not an option in code, so you change it without shipping your app, and it reaches each browser with its next session.

**Sypnia Cloud**

Change it in the project's settings in the app, or with the API and an API token that has the `admin` scope:

```bash
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"replay": {"sample_rate": 0.25}}}'
```

**Self-hosted**

With the API and an API token that has the `admin` scope, or the root token:

```bash
curl -X PATCH "https://sypnia.example.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"replay": {"sample_rate": 0.25}}}'
```

**You should see:**`200` and the project, with `"sample_rate": 0.25` under `settings.replay`.

| Setting                 | Type           | Default | Meaning                                                                                                                           |
| ----------------------- | -------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `replay.sample_rate`    | number, 0 to 1 | `0.1`   | The share of sessions recorded from their start. `0` records only sessions where something goes wrong. `1` records every session. |
| `replay.always_record`  | list           | `[]`    | Persons and accounts whose sessions are always recorded. See below.                                                               |
| `replay.blocked_routes` | list of routes | `[]`    | Routes where nothing is recorded. See [Privacy and masking](https://docs.sypnia.com/sdks/privacy-and-masking).                    |
| `replay.mask_all_text`  | boolean        | `false` | Masks every text in every recording.                                                                                              |
| `snapshots.sample_rate` | number, 0 to 1 | `0.5`   | The share of sessions that take page snapshots for click maps.                                                                    |

To switch recording off for good in one app, whatever the project says, pass `replay: false` to `init`: the recorder is then never loaded.

### Always record a person or an account

```bash
curl -X PATCH "https://api.sypnia.com/v1/projects/shop" \
  -H "Authorization: Bearer $SYPNIA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"replay": {"always_record": [
        {"person": "u_1042", "note": "Reported the checkout bug", "until": "2026-03-26T00:00:00Z"}
      ]}}}'
```

Each rule names a `person` or an `account` by the id your app passes to [`identify()`](https://docs.sypnia.com/sdks/identifying-people), and may carry a `note` and an `until` date after which it stops. The rule applies from that person's next session. Within a session that is already running, it applies from the moment the person is identified, if the SDK had not asked before. On a self-hosted engine use your own base URL.

## The «slow down» signal

Every answer from ingest says how many events were stored and how many were not, and why. When the project has reached a limit, the answer also carries `slow_down`:

```json
{
  "accepted": 1,
  "dropped": 1,
  "dropped_reasons": { "limit_reached": 1 },
  "slow_down": {
    "reason": "events_limit",
    "send": "failures",
    "replay": false,
    "until": "2026-04-01T00:00:00Z"
  }
}
```

The SDKs obey it at once and remember it until `until`, in every tab:

| In the signal      | What the SDK does                                                                                                                                                                                                                                                                                                               |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `send: "failures"` | It sends failures only: errors, failed API calls, and on the server the requests that failed with their spans. It also keeps sending what ties a failure to a visit and a person: session starts, page views and `identify`. It stops sending performance values, successful requests, clicks, form failures and custom events. |
| `replay: false`    | It stops recording and uploading. A session that would have been recorded gets a marker saying so (`replay_gap`, reason `limit`), so its timeline tells you.                                                                                                                                                                    |
| `until`            | When to go back to normal. The SDK asks again at the start of the next session after that time.                                                                                                                                                                                                                                 |

The same object comes with the per-session settings the SDK reads at the start of each session, so a browser that opens your app after the limit was reached never starts sending what would be refused.

A burst is a different thing. If one address sends too fast with one key, ingest answers `429` with `Retry-After`. The SDK waits that long, at most 60 seconds, and sends the same batch again once.

## What happens at a limit

|                        | Sypnia engine (open source, self-hosted)                                     | Sypnia Cloud (paid service, with a free tier)                                                                            |
| ---------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Where limits come from | Nowhere, unless you set a quota for a project in the engine's configuration. | Your plan: events a month and replays a month.                                                                           |
| At 80 %                | An alert is recorded, and sent to your webhook if you set one.               | The organization's owners get an alert by e-mail and in the app.                                                         |
| At 100 % of events     | Ingest sends slow_down. Failures are still stored.                           | Ingest sends slow_down until the month ends. Failures are still stored, so a new problem still appears and still alerts. |
| At 100 % of replays    | Ingest tells the SDKs to stop recording.                                     | Ingest tells the SDKs to stop recording until the month ends. Sessions are still listed with their full timeline.        |
| What you can read      | Usage counters through the API and the CLI.                                  | Usage counters in the app and through the API, with how many events were not stored.                                     |

What counts as an event on Sypnia Cloud is narrow: an error, a trace, or a performance value. Page views, clicks, form failures and custom events are free. The exact rules and the numbers of each plan are in [Plans and limits](https://docs.sypnia.com/cloud/plans-and-limits); the quotas of a self-hosted engine are in its [configuration](https://docs.sypnia.com/self-hosting/configuration).

## Send less on purpose

Before a limit is the better time to choose what matters:

| To reduce                         | Do                                                                                                                         |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Server traces                     | Add noisy routes to `ignoreRoutes` in the [Node SDK](https://docs.sypnia.com/sdks/node): health checks, polling endpoints. |
| Browser requests                  | Add polling calls to `ignoreRequests`.                                                                                     |
| Errors you will never fix         | Add them to `ignoreErrors`, or mark the problem as ignored.                                                                |
| Performance values                | `capture: { vitals: false }` in the browser SDK.                                                                           |
| Replays                           | Lower `replay.sample_rate`. Sessions with trouble are still recorded.                                                      |
| Everything from a part of the app | `ignoreRoutes`.                                                                                                            |

## Check what applies to a session

Set `debug: true`. At the start of a session the SDK prints the decision it received, for example `replay: buffer (sample_rate 0.1)`, and any `slow_down` in force.

## Next
