# How to control which sessions you record - Docs

There are several ways to control which sessions you record:

## Programmatically start and stop recordings

Most users should initialize PostHog with the default settings (which starts recording automatically) and use the other options on this page — like [URL triggers](#with-url-trigger-conditions), [event triggers](#with-event-trigger-conditions), [feature flags](#with-feature-flags), or [sampling](#sampling) — to control what gets recorded. Manual control is only needed for advanced use cases where you need to programmatically start and stop recording at specific points in your application.

## Web

1.  For older projects, there is a section for 'Authorized domains for replay' in the [project replay settings](https://us.posthog.com/settings/environment-replay#replay-authorized-domains). Ensure your domain is added if the section is present.

2.  Set `disable_session_recording: true` in your [config](/docs/libraries/js/config.md).

Web

PostHog AI

```javascript
posthog.init('<ph_project_token>', {
  api_host: 'https://us.i.posthog.com',
  defaults: '2026-01-30',
    disable_session_recording: true,
    // ... other options
})
```

3.  Manually start recording by calling `posthog.startSessionRecording()`. Similarly, you can stop the recording at any point by calling `posthog.stopSessionRecording()`.

By default, `startSessionRecording` obeys any ingestion controls you've set - so you might call start and not record a session because of sampling or some other control.

You can pass override options to `startSessionRecording` to change this.

PostHog AI

```
posthog.startSessionRecording(true) // start ignoring all ingestion controls
posthog.startSessionRecording({
  // you don't have to send all of these
  sampling: true || false;
  linked_flag: true || false;
  url_trigger: true || false;
  event_trigger: true || false
})
```

> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).

## iOS

> Requires PostHog iOS SDK version >= [3.19.0](https://github.com/PostHog/posthog-ios/releases/tag/3.19.0).

Setting `config.sessionReplay = false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.

You can manually control when to start and stop session recordings using the following methods:

-   `startSessionRecording(resumeCurrent: Bool)`
    -   Set **resumeCurrent** to `true` to resume a previous session recording (Default).
    -   Set **resumeCurrent** to `false` to start a new session recording.
-   `stopSessionRecording()`
    -   Stops/pauses the current session recording.

> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).

## Android

> Requires PostHog Android SDK version >= [3.16.0](https://github.com/PostHog/posthog-android/releases/tag/3.16.0).

Setting `config.sessionReplay = false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.

You can manually control when to start and stop session recordings using the following methods:

-   `startSessionReplay(resumeCurrent: Boolean)`
    -   Set **resumeCurrent** to `true` to resume a previous session recording (Default).
    -   Set **resumeCurrent** to `false` to start a new session recording.
-   `stopSessionReplay()`
    -   Stops/pauses the current session recording.

> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).

## React Native

> Requires `posthog-react-native` >= [4.36.0](https://github.com/PostHog/posthog-js/releases) and `posthog-react-native-session-replay` >= [1.3.0](https://github.com/PostHog/posthog-react-native-session-replay/releases).

Setting `sessionReplay` to `false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.

You can manually control when to start and stop session recordings using the following methods:

-   `startSessionRecording(resumeCurrent?: boolean)`
    -   Set **resumeCurrent** to `true` to resume a previous session recording (Default).
    -   Set **resumeCurrent** to `false` to start a new session recording.
-   `stopSessionRecording()`
    -   Stops/pauses the current session recording.

typescript

PostHog AI

```typescript
// Start recording (resume current session)
await posthog.startSessionRecording()
// Start recording with a new session
await posthog.startSessionRecording(false)
// Stop recording
await posthog.stopSessionRecording()
```

> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).

## Flutter

> Requires PostHog Flutter SDK version >= [5.14.0](https://github.com/PostHog/posthog-flutter/releases/5.14.0). Available on iOS, Android, and Web.

Setting `config.sessionReplay = false` in your PostHog configuration will prevent PostHog from automatically starting session recordings on SDK setup.

You can manually control when to start and stop session recordings using the following methods:

-   `startSessionRecording({bool resumeCurrent = true})`
    -   Set **resumeCurrent** to `true` to resume a previous session recording (Default).
    -   Set **resumeCurrent** to `false` to start a new session recording.
-   `stopSessionRecording()`
    -   Stops/pauses the current session recording.

> **Note:** Calling these methods will have no effect if session recordings are disabled in your PostHog [Project Settings](https://app.posthog.com/project/settings).

## With URL trigger conditions

You can opt to only start recordings once your user visits a certain page. After the URL matches, the recording continues even after they leave the matching page. The client keeps a buffer in-memory (see [how the buffer works](#how-the-trigger-buffer-works) below), so you'll still be able to see how they arrived at the page.

![Adding URL trigger to control session recordings](https://res.cloudinary.com/dmukukwp6/image/upload/replay_url_trigger_light_bc6130e3d0.png)![Adding URL trigger to control session recordings](https://res.cloudinary.com/dmukukwp6/image/upload/replay_url_trigger_dark_9c6ebb6c37.png)

## With Event trigger conditions

Since posthog-js version 1.186.0, you can opt to only start recordings once your user emits a particular event. After the event is captured, the recording continues even after they leave the matching page. The client keeps a buffer in-memory (see [how the buffer works](#how-the-trigger-buffer-works) below), so you'll still be able to see activity leading up to that event.

![Adding event trigger to control session recordings](https://res.cloudinary.com/dmukukwp6/image/upload/event_trigger_light_21a531edbb.png)![Adding event trigger to control session recordings](https://res.cloudinary.com/dmukukwp6/image/upload/event_trigger_dark_f67b3ffb30.png)

### Triggering on exceptions

If you use [error tracking](/docs/error-tracking.md), exceptions are captured as events. You can select the exception event as an event trigger to start session recording.

![Triggering session recordings on exceptions](https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/replay_on_exception_light_4a88e6f239.png)![Triggering session recordings on exceptions](https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/replay_on_exception_dark_621ce757d3.png)

### How the trigger buffer works

When using URL or event triggers, the client buffers recording data in-memory while waiting for a trigger to match. Here's how it works:

-   While waiting for a trigger ("trigger pending"), the client takes a **full snapshot once per minute**
-   Only data from the **most recent snapshot** up to when the trigger fires is kept
-   This means the buffer contains **up to 1 minute** of activity before the trigger

The actual buffered duration varies depending on timing. For example:

-   If a snapshot was taken 45 seconds before the trigger fires, you'll see ~45 seconds of activity before the trigger
-   If a snapshot was taken 5 seconds before the trigger fires, you'll only see ~5 seconds of activity

This approach balances providing useful context with browser performance — keeping multiple snapshots would be more expensive for the browser.

> **Note:** Full page navigations (page refreshes) clear the buffer and start over from a new snapshot.

## With feature flags

You can select a [feature flag](/docs/feature-flags.md) to control whether to record sessions or not. Recordings will only be collected for users when the flag is enabled for them.

1.  [Create a boolean or multiple variant flag](/docs/feature-flags/creating-feature-flags.md) that determines whether to record sessions or not.
2.  Go to the [replay ingestion settings page](https://us.posthog.com/replay/settings#selectedSetting=replay-triggers).
3.  Link your newly created flag in the **Enable recordings using feature flag**.

![Selecting a feature flag to control session recordings](https://res.cloudinary.com/dmukukwp6/image/upload/v1725441098/posthog.com/contents/Screenshot_2024-09-04_at_10.11.12_AM.png)![Selecting a feature flag to control session recordings](https://res.cloudinary.com/dmukukwp6/image/upload/v1725441098/posthog.com/contents/Screenshot_2024-09-04_at_10.11.20_AM.png)

## Sampling

Sampling enables you to record a percentage of all sessions. To set a sampling rate, go to the [replay ingestion settings page](https://us.posthog.com/replay/settings#selectedSetting=replay-triggers).

Sampling is supported on the following SDKs:

-   **Web** - posthog-js 1.85.0+
-   **Android** - 3.34.0+
-   **iOS** - 3.42.0+
-   **React Native** - 4.37.0+

![Sampling config shown set to 100% i.e. no sampling](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/sampling-config-light-mode.png)![Sampling config shown set to 100% i.e. no sampling](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/sampling-config-dark-mode.png)

Our recommendation is to start with capturing 100% of sessions and decrease it as needed. This helps you get a sense of how many sessions you’re recording and how much data you’re collecting.

### How sampling works

Sampling is deterministic based on the session ID. When a new session starts, PostHog converts the session ID into a number between 0 and 1 using a hash function. This number is then compared to your configured sample rate (for example, 0.1 for 10% or 0.2 for 20%).

If the generated number is less than the sample rate, the session is recorded. Because the same session ID always produces the same number, the decision to record or not is consistent throughout the session's lifetime.

This means:

-   Sessions are selected based on their ID, not by time period or order
-   The same session will always get the same recording decision, even across page refreshes
-   At 20% sampling, roughly 20% of your unique sessions will be recorded, distributed evenly across your traffic

> **Note:** Sampling reduces the number of sessions you record, but you cannot control which specific sessions are selected — the selection is determined by the session ID hash.

## Combining controls

Since version 1.238.0 of the web SDK you can control how multiple triggers are combined. Choosing whether recording will start when all triggers match or when any trigger matches.

For example if you set an event trigger for Exception events, a URL trigger for the checkout page, and sampling to 20%.

### With any matching

You'll capture 20% of every session, and any session that has an exception event or is on the checkout page.

### With all matching

You'll capture 20% of any session on the checkout page that has an exception event.

## Minimum duration

In your [replay ingestion settings](https://us.posthog.com/settings/project-replay#replay-ingestion), you can set a minimum duration for sessions to be recorded.

![Minimum duration config shown set to 2 seconds](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/min-duration-light-mode.png)![Minimum duration config shown set to 2 seconds](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/tutorials/limit-session-recordings/min-duration-dark-mode.png)

There are two modes for how minimum duration is enforced, controlled by the `strictMinimumDuration` configuration option. This is useful if you want to exclude sessions that are too short to be useful. For example, you might want to exclude sessions that are less than 2 seconds long to avoid recording sessions where users quickly bounce off your site.

### Legacy mode (default)

In legacy mode (`strictMinimumDuration: false` or not set), the minimum duration is checked against the **total session age**. When a session starts, the browser records the start time. If the minimum duration has passed since the session start time, the recording data is sent to the backend.

Web

PostHog AI

```javascript
posthog.init('<ph_project_token>', {
  api_host: 'https://us.i.posthog.com',
  session_recording: {
    strictMinimumDuration: false
  }
})
```

**Limitation**: If you set a high minimum duration and your user visits multiple pages (causing full page refreshes), the in-memory buffer may be cleared by navigation. When the session reaches the minimum age, we'll start sending data, but you might miss the beginning of the session because the buffer was cleared by the page refresh.

For example, with a 12 second minimum:

-   User visits page A for 6 seconds, then navigates to page B
-   After 6 more seconds on page B (12 seconds total session age), we start sending the recording
-   Result: You get 6 seconds of recording from page B, but miss the 6 seconds from page A

### Strict mode (available in 1.291.0+)

In strict mode (`strictMinimumDuration: true`), the minimum duration is checked against the **actual buffered recording data** (from first to last timestamp), not the session age. We only start sending the recording once we have the minimum duration of continuous data in the buffer.

**Note**: This will become the default behavior in a future release. To opt in now, add to your config:

Web

PostHog AI

```javascript
posthog.init('<ph_project_token>', {
  api_host: 'https://us.i.posthog.com',
  session_recording: {
    strictMinimumDuration: true
  }
})
```

**Key difference**: If the user navigates to a new page before reaching the minimum duration, the buffer is cleared and we start over. The recording will only be sent once we have enough **continuous data** on a single page.

For example, with a 12 second minimum:

-   User visits page A for 6 seconds, then navigates to page B
-   The buffer is cleared on navigation
-   User must stay on page B for 12 seconds before we start sending the recording
-   Result: You get the full recording from page B once it reaches 12 seconds

Once a session has passed the minimum duration threshold on any page, subsequent page navigations in the same session will continue to send recordings **immediately**.

This mode is **more accurate** for filtering out short sessions, especially on sites with full page refreshes, but may result in missing more session data if users **bounce quickly** across multiple pages.

### Choosing the right mode

-   **Use legacy mode** if you want to capture as much session data as possible and are okay with potentially missing early parts of sessions after page refreshes
-   **Use strict mode** if you want to ensure you only record sessions where users actually spend the minimum duration on a single page, accepting that you may miss more bouncing users

## Billing Limits

You can set a [billing limit](/docs/billing/limits-alerts.md). We'll stop ingesting recordings when you reach your limit.

### Community questions

Ask a question

### Was this page useful?

HelpfulCould be better