Replay Search API

How the Replay Search API works

The API runs a query against Amplitude Analytics to find sessions matching your filters, then looks up Session Replay recordings for those sessions. The analytics query caps results at 1,000 sessions, so replay-level filters like duration apply to that capped set. The response metadata surfaces pre- and post-filter counts so you can tell when the cap affected your results.

Request

Full request shape

{
  "start": "20260313",
  "end": "20260320",

  "userFilters": [
    {"type": "cohort", "cohortId": "abc123"},
    {"type": "property", "prop": "country", "op": "is", "values": ["United States"]}
  ],

  "eventFilters": [
    {
      "eventType": "Purchase",
      "op": "greater or equal",
      "count": 1,
      "filters": [
        {"type": "event", "prop": "page", "op": "is", "values": ["checkout"]},
        {"type": "user", "prop": "country", "op": "is", "values": ["United States"]}
      ]
    }
  ],

  "replayFilters": [
    {"prop": "duration", "op": "greater or equal", "values": ["10"]},
    {"prop": "sentiment", "op": "is", "values": ["positive"]}
  ],

  "groupBys": {
    "eventPosition": "last",
    "properties": [
      {"type": "user", "value": "country"},
      {"type": "event", "value": "platform"}
    ]
  },

  "limit": 10
}

Fields

start / end (string, required) : Date range in YYYYMMDD format.

userFilters (array, optional) : Filters that narrow the set of users whose sessions are returned. All entries are AND'd together. Two types are supported:

Cohort filter:

{"type": "cohort", "cohortId": "abc123"}

Supports "negated": true to exclude cohort members.

Property filter:

{"type": "property", "prop": "country", "op": "is", "values": ["United States"]}

The property must match on at least one event in the session and must never not-match on any event in the session. This requirement confirms the property held true throughout the session, which matters for properties that can change mid-session, such as plan tier.

eventFilters (array, optional) : Filters on event occurrence within the session. Each entry specifies an event type and a count condition that the session must satisfy. If you specify Item Purchased >= 1 and Add to Cart >= 2, Amplitude guarantees the returned replays are for sessions where at least one Item Purchased event and at least two Add to Cart events occurred.

replayFilters (array, optional) : Filters on replay-level properties. The backend determines which filters apply during the session query (pre-filters) and which apply after replay retrieval (post-filters). The response metadata reflects this distinction. Supported properties:

groupBys (object, optional) : Enriches each session in the response with specified property values.

limit (number, optional, default: 10) : Maximum number of sessions to return.

Response

Full response shape

{
  "data": [
    {
      "amplitude_id": "123456789",
      "session_replay_id": "abc-def-ghi",
      "session_start_time": 1742860800000,
      "session_end_time": 1742861243000,
      "duration": 443,
      "url": "https://app.amplitude.com/...",
      "groupBys": {
        "country": "United States"
      }
    },
    {
      "amplitude_id": "987654321",
      "session_replay_id": "xyz-uvw-rst",
      "session_start_time": 1742774400000,
      "session_end_time": 1742774821000,
      "duration": 421,
      "url": "https://app.amplitude.com/...",
      "groupBys": {
        "country": "Germany"
      }
    }
  ],
  "metadata": {
    "pre_filter_count": 1000,
    "pre_filter_capped": true,
    "post_filters_applied": ["duration"],
    "post_filter_count": 2,
    "limit": 10
  }
}

Session fields

Each object in data includes:

metadata fields

Pre-filter and post-filter counts

The API caps the initial session query at 1,000 sessions. Post-filters (such as duration) apply to that capped set. If pre_filter_capped is true and post_filters_applied is non-empty, additional matching sessions beyond the cap may exist that the API didn't evaluate.

For example, if pre_filter_count is 1000, pre_filter_capped is true, and post_filter_count is 2, narrow your date range or event filters to reduce the pre-filter population.

Limitations and future work

• Pagination: The API doesn't support pagination. The 1,000-session pre-filter cap combined with post-filtering can produce sparse results for broad queries. Narrow your date range or add event filters to reduce the pre-filter population.
• Funnel-based session search: Finding replays for funnel conversion or drop-off is a distinct use case with different semantics. Funnel-based session search warrants its own endpoint and isn't supported here.
• Ordered event sequences: Optional step ordering (for example, "event A then event B") isn't supported yet.