---
title: Replay Search API
description: "Use the Replay Search API to find sessions from Session Replay matching user properties, cohort membership, event occurrence, or replay characteristics such as duration and sentiment."
product: session-replay
token_estimate: 1794
---
# Replay Search API

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

## 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

```json
{
  "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:_

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

Supports `"negated": true` to exclude cohort members.

_Property filter:_

```json
{"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.

| Field | Description |
| --- | --- |
| `eventType` | The event name, or `"_all"` to match any event. |
| `op` | One of `"greater or equal"`, `"greater"`, `"less or equal"`, `"less"`, `"is"`, `"is not"`. |
| `count` | Integer threshold. |
| `filters` | Optional array of property conditions scoped to this event. `type` is `"event"` or `"user"`. |

`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:

| `prop` | Description | Filter timing |
| --- | --- | --- |
| `duration` | Replay duration in seconds | Post |
| `sentiment` | User feedback sentiment | Pre |

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

| Field | Description |
| --- | --- |
| `eventPosition` | `"first"` or `"last"`. Controls which event in the session to read property values from. Applies to all properties. |
| `properties` | Array of \`{"type": "user" |

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

---

## Response

### Full response shape

```json
{
  "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:

| Field | Type | Description |
| --- | --- | --- |
| `amplitude_id` | string | Amplitude user ID. |
| `session_replay_id` | string | Unique identifier for the replay. |
| `session_start_time` | number | Session start time in milliseconds since epoch. |
| `session_end_time` | number | Session end time in milliseconds since epoch. |
| `duration` | number | Session duration in seconds. |
| `url` | string | Direct link to the replay in Amplitude. |
| `groupBys` | object | Property values requested through `groupBys`, keyed by property name. |

### `metadata` fields

| Field | Type | Description |
| --- | --- | --- |
| `pre_filter_count` | number | Number of sessions matched before post-filters applied. Capped at 1000. |
| `pre_filter_capped` | boolean | `true` if the pre-filter result hit the 1000-session cap. When `true` and `post_filters_applied` is non-empty, the returned sessions may not represent the full matching population. |
| `post_filters_applied` | string\[\] | Names of `replayFilters` applied as post-filters. |
| `post_filter_count` | number | Number of sessions remaining after post-filters applied. |
| `limit` | number | The limit applied to the response. |

### 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; this API doesn't support it.
- **Ordered event sequences**: The API doesn't support optional step ordering yet (for example, "event A then event B").