experiments

Session recordings of this experiment matching a bucket.

Answers the questions a recordings query can't express on its own — "fired any of these metrics", "fired none of them", "was exposed but never completed the funnel in this session" — by returning a bounded, most-recent-first list of session IDs to pass back as a recordings query's session_ids. POST because the metric list doesn't fit a query string; the endpoint only reads.

Session-scoped and goal-free: the set describes what happened in each session, while the experiment analysis counts per person over the whole run window. A session can be in the drop-off bucket while the same person converts in a later one.

post/api/projects/{project_id}/experiments/{id}/session_buckets/

Request

  • Base URL: https://us.posthog.com
  • URL: https://us.posthog.com/api/projects/{project_id}/experiments/{id}/session_buckets/
  • Auth: HTTP bearer

Path parameters

idinteger required

A unique integer value identifying this experiment.

project_idstring required

Project ID of the project you're trying to access. To find the ID of the project, make a call to /api/projects/.

Request body

bucket'fired_any' | 'no_metric_activity' | 'funnel_dropoff' required
  • fired_any - fired_any
  • no_metric_activity - no_metric_activity
  • funnel_dropoff - funnel_dropoff
metric_uuidsstring[]

Metrics the bucket is computed over. Exactly one funnel metric for 'funnel_dropoff'. Omit for the other buckets to use every metric of the experiment that can be matched to recordings.

variantstring nullable

Restrict to sessions that saw this variant. Omit for every variant. A session that saw more than one variant matches each variant it saw.

limitinteger

Maximum session IDs to return, at most 100. The most recently active matching sessions win.

Response

session_idsstring[] required

IDs of matching sessions that have a recording, most recently active first. Feed these to a recordings query as session_ids; they are a subset of the experiment's exposed sessions, so the exposure filter can stay in place alongside them.

truncatedboolean required

True when more sessions matched than the limit returned. Older matches were dropped first.

date_fromstring date-time required

Start of the window scanned, never before the experiment started. At most 30 days before date_to when the scan found an exposure to anchor on. When it found none, how far back the search for one reached, which the project's recording retention bounds. Matches outside the window are not returned.

date_tostring date-time required

End of the window scanned: 24 hours after the latest exposure captured in a session, capped at the experiment's end date or now. The pad covers the metric events a session fires after its exposure. The scan ends at the experiment's end date, or now while it runs, when that exposure can't be located, so an experiment whose exposures stopped long ago is still scanned where its sessions are.

filter_test_accountsboolean required

Whether the project's test-account filters were applied, following the experiment's exposure criteria, the same rule the experiment's recordings list uses.

used_exposure_fallbackboolean required

True when the exposed population was matched on the stamped $feature/<flag key> event property instead of the exposure event, because the default exposure event has only ever been captured server-side and can never match a session. The sessions then mean 'the flag was active in this session', not 'the exposure moment was captured'. The variant comes from the flag's value on each event, so a returning user can appear under a variant they were re-bucketed into later.

Changes

No recorded changes to this operation across all 1 revision of this API.