Search replays with the API

For an interactive investigation in Amplitude, find replays with search filters. Use this API when your application or agent needs to retrieve matching replay links.

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

POST https://amplitude.com/api/1/replay-search

For EU data residency, use https://eu.amplitude.com/api/1/replay-search instead.

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 users in the returned sessions. Amplitude combines all entries with AND. Choose either of these filter types:

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

• 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. This API doesn't support funnel-based session search. To investigate conversion or drop-off in Amplitude, open replays from a Funnel Analysis chart.
• Ordered event sequences: The API doesn't support optional step ordering (for example, "event A then event B").