リプレイ検索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 で結合されています。 次の 2 つのタイプがサポートされています。

コホートフィルタ：

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

コホートメンバーの除外"negated": trueをサポートします。

プロパティフィルタ：

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

このプロパティは、セッション内の少なくとも1つのイベントで一致している必要があります。また、セッション内のどのイベントでも一致していないことがあってはなりません。この要件は、セッション全体でプロパティが有効であることを確認します。これは、プラン階層など、セッション中に変更される可能性があるプロパティにとって重要です。

eventFilters（配列、オプション） : セッション内のイベント発生状況をフィルタリングします。 各エントリは、セッションが満たさなければならないイベントタイプとカウント条件を指定します。Item Purchased >= 1およびAdd to Cart >= 2を指定した場合、Amplitudeは少なくとも1件のItem Purchasedイベントと2件以上の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」)。