Replay Search API

Replay Search API의 작동 방식

API는 Amplitude 애널리틱스에 대해 쿼리를 실행하여 필터와 일치하는 세션을 찾은 다음 해당 세션에 대한 세션 리플레이 기록을 검색합니다. 분석 쿼리는 결과를 1,000개 세션으로 제한하므로 duration과 같은 재생 수준 필터는 해당 제한된 세트에 적용됩니다. 응답 메타데이터는 필터 전/후 수를 표시하므로 상한이 결과에 언제 영향을 미쳤는지 알 수 있습니다.

요청

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

EU 데이터 레지던시의 경우 https://eu.amplitude.com/api/1/replay-search을 대신 사용하십시오.

전체 요청 구조

{
  "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
}

필드

start / end (문자열, 필수) : YYYYMMDD 형식의 날짜 범위입니다.

userFilters (어레이, 선택 사항) : 세션이 반환되는 사용자 집합을 좁히는 필터입니다. 모든 항목은 AND로 묶여있습니다. 두 가지 유형이 지원됩니다.

코호트 필터:

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

"negated": true을(를) 사용하여 코호트 구성원을 제외할 수 있습니다.

속성 필터:

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

속성은 세션의 적어도 하나의 이벤트에서 일치해야 하며 세션의 전체 이벤트에서 일치하지 않는 경우가 절대 없어야 합니다. 이 요구 사항은 세션 내내 해당 속성이 유효함을 확인합니다. 이는 플랜 티어와 같이 세션 도중에 변경될 수 있는 속성에 중요합니다.

eventFilters (어레이, 선택 사항) : 세션 첫 사용 후 발생한 이벤트를 필터링합니다. 각 항목은 이벤트 유형과 세션이 충족해야 하는 수행 회수가 조건을 지정합니다.Item Purchased >= 1 및 Add to Cart >= 2을(를) 지정하면 Amplitude는 반환된 재생이 하나 이상의 Item Purchased 이벤트와 두 개 이상의 Add to Cart 이벤트가 발생한 세션에 대한 것임을 보장합니다.

replayFilters (어레이, 선택 사항) : 재생 수준의 속성에 대한 필터링입니다. 백엔드는 세션 쿼리 다음 기간동안 적용할 필터(사전 필터)와 재생 검색 후에 적용할 필터(사후 필터)를 결정합니다. 응답 metadata은 이러한 차이를 반영합니다. 지원되는 속성

groupBys (객체, 선택 사항) : 응답의 각 세션을 지정된 속성 값으로 보강합니다.

limit (숫자, 선택 사항, 기본값: 10) : 반환할 최대 세션 수입니다.

응답

전체 응답 구조

{
  "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
  }
}

세션 필드

data의 각 객체에는 다음이 포함됩니다.

metadata 필드

사전 필터 및 사후 필터 수

API는 초기 세션 쿼리의 최대 수를 1,000개 세션으로 제한합니다. 사후 필터(예: duration)는 해당 캡이 설정된 세트에 적용됩니다. pre_filter_capped이(가) true이고 post_filters_applied이(가) 비어 있지 않은 경우, API가 평가하지 않은, 상한을 초과하는 추가 일치 세션이 있을 수 있습니다.

예를 들어 pre_filter_count이(가) 1000이고 pre_filter_capped이(가) true, post_filter_count이(가) 2인 경우, 날짜 범위 또는 이벤트 필터를 좁혀 사전 필터링 대상 수를 줄이십시오.

한계와 향후 작업

• 페이지 지정: API는 페이지 지정을 지원하지 않습니다. 1,000개 세션의 사전 필터링 제한을 사후 필터링과 결합하면 광범위한 쿼리에 대해 희소한 결과가 생성될 수 있습니다. 날짜 범위를 좁히거나 이벤트 필터를 추가하여 사전 필터링 모집단을 줄이십시오.
• 퍼널 기반 세션 검색: 퍼널 전환 또는 드롭오프를 위해 재생을 찾는 것은 의미론이 다른 독특한 활용 사례입니다. 퍼널 기반 세션 검색은 별도의 엔드포인트가 필요하며, 이 API는 이를 지원하지 않습니다.
• 순서화된 이벤트 시퀀스: API는 아직 선택적 단계 순서를 지원하지 않습니다(예: "이벤트 A 후 이벤트 B").