How to control which sessions you record

There are several ways to control which sessions you record with the Web JavaScript SDK:

Programmatically start and stop recordings

Note: For mobile replay controls, see iOS, and Android privacy controls section. Support for this method in React Native and Flutter is planned — track progress here.

1. For older projects, there is a section for 'Authorized domains for replay' in the project replay settings. Ensure your domain is added if the section is present.

2. Set disable_session_recording: true in your config.

posthog.init('<ph_project_api_key>', {
  api_host: 'https://us.i.posthog.com',
  defaults: '2025-05-24',
    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.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 
})

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 short buffer in-memory, so you'll still be able to see how they have arrived at the page.

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 short buffer in-memory, so you'll still be able to see how they have arrived at the event.

Triggering on exceptions

If you use error tracking, exceptions are captured as events. You can select the exception event as an event trigger to start session recording.

With feature flags

You can select a feature flag 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 that determines whether to record sessions or not.
2. Go to the replay ingestion settings page.
3. Link your newly created flag in the Enable recordings using feature flag.

Sampling

Sampling enables you to record a percentage of all sessions. To set a sampling rate, go to the replay ingestion settings page.

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.

Note: Sampling reduces the number of sessions you record, but it doesn’t let you control which sessions are recorded.

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, you can set a minimum duration for sessions to be recorded.

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.

posthog.init('<ph_project_api_key>', {
  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:

posthog.init('<ph_project_api_key>', {
  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. We'll stop ingesting recordings when you reach your limit.