公開 API と API キー

1. 概要

MousePlayer API を使うと、ワークスペースのデータを独自のダッシュボード、データウェアハウス、社内ツールに取り込めます。セッションへの顧客 ID の付加（identify。書き込み範囲のキーが必要です。「キーの範囲」を参照）を除き、 読み取り専用です。API を通じたデータの変更や削除はできません。

ベース URL： https://www.mouseplayer.com/api/v1/
すべてのレスポンスは JSON です。
すべてのリクエストは API キーで認証され、そのキーが所属するワークスペースに自動的に限定されます — あるワークスペースのキーで、別のワークスペースのデータが見えることは、偶然でもありません。
セッション再生の録画全体（マウス移動、DOM スナップショット）は API から 取得できません 。セッションのメタデータ、ページビュー、カスタムイベント、セグメントを取得できます — 生の再生ペイロードを持ち回らずに、レポートやダッシュボードを作るのに十分な情報です。

2. 認証

アカウントメニューの API キー （/api-keys）で API キーを作成・管理します。キーを作成または取り消せるのは、ワークスペースのオーナーと管理者だけです。

キーを秘密に保ってください。 キーはワークスペース内のすべてへの読み取り権限を与えます。完全なキーが表示されるのは、作成直後の1回だけです — パスワードマネージャーやシークレット保管庫に保存してください。紛失したら取り消し、新しいキーを作成してください。

リクエストごとに、キーを Bearer トークンとして Authorization ヘッダーに入れて送信します。

# List projects in your workspace curl -H "Authorization: Bearer mp_live_..." \ https://www.mouseplayer.com/api/v1/projects

キーがない、不正な形式、または取り消されている場合、次の 401 レスポンスを返します。

{ "error": "Invalid or missing API key. Use: Authorization: Bearer <key>" }

必要なプラン

REST API は、 Business と Enterprise プランに含まれます。適用するプランは、ワークスペースの オーナー のプランで、招待されたチームメンバーも引き継ぎます。確認はキー作成時だけでなく、 リクエストのたびに行います — ワークスペースのプランを下げると、既存のキーも動作しなくなり、次を返します： 403。

キーの範囲

キーの範囲はキー自身のプレフィックスに含まれます。見ただけで役割が分かります — 次の中でも、 .env、チケットやターミナルでも同様です。

プレフィックス	意味
`mp_ro_`	読み取り専用。プロジェクト、セッション、イベント、セグメントを読み取れます。何も変更できません。
`mp_rw_`	読み取りと書き込み。上記すべてに加え、identify エンドポイント経由で顧客 ID を付加できます。

キー作成時に範囲を選びます。初期設定は読み取り専用です。書き込み用エンドポイントで読み取り専用キーを使うと、 403 が返り、キーの範囲とエンドポイントに必要な範囲を示すメッセージが付きます。後から範囲は変更できません — 新しいキーを作成し、古いキーを取り消してください。

3. レート制限

API キーごとの上限は、 1分間に60リクエストで、移動時間窓で追跡します。超過すると、その時間窓が空くまで、リクエストには次の 429 レスポンスを返します。

{ "error": "Rate limit exceeded. Max 60 requests per minute." }

より高い上限が必要なものを開発中の場合は、サポートへ用途をお知らせください。

4. エンドポイント

GET/api/v1/projects

ワークスペースのすべてのプロジェクト（トラッキング対象のプロパティ）を一覧表示します。

{ "data": [ { "channelid": "955a45df5ee842cb", "domain": "yourdomain.com", "status": "active", "total_traffic_bytes": 27304765, "created_at": "2026-07-19 22:06:39", "last_used": "2026-08-05 01:12:55" } ] }

GET/api/v1/projects/{channelid}/sessions

プロジェクトで録画した訪問者セッションを、新しい順に一覧表示します。ページ分割されます。

クエリパラメーター	説明
`page`	ページ番号。初期値は `1`。
`per_page`	1ページあたりの件数。初期値は `25`、最大は `100`。
`since`	この日付以降に開始したセッションのみ（`YYYY-MM-DD`）。
`until`	この日付以前に開始したセッションのみ。

{ "data": [ { "session_id": "s_kfmist058_1785795295504", "visitor_id": "v_sv90jdpzo_1785795296042", "custom_user_id": null, "country": "DE", "device_type": "desktop", "is_bot": 0, "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105 } ], "pagination": { "page": 1, "per_page": 25, "total": 142, "total_pages": 6 } }

GET/api/v1/sessions/{session_id}

一つのセッションのメタデータとページビューです。再生ペイロード全体は意図的に除外しています — 再生にはダッシュボードのプレーヤーを使ってください。

{ "data": { "session_id": "s_kfmist058_1785795295504", "channelid": "955a45df5ee842cb", "visitor_id": "v_sv90jdpzo_1785795296042", "country": "DE", "asn_org": "Deutsche Telekom AG", "referrer": "https://duckduckgo.com/", "device_type": "desktop", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41", "duration_seconds": 105, "pageviews": [ { "pageview_id": 1199, "url": "https://yourdomain.com/pricing", "page_title": "Pricing", "start_time": "2026-08-04 00:14:56", "end_time": "2026-08-04 00:16:41" } ] } }

GET/api/v1/sessions/{session_id}/events

セッション中に発生したカスタムイベント（次で送信するものと同じイベント： mp('event', ...)）と、そのパラメーターです。

{ "data": [ { "event_id": 61, "pageview_id": 1199, "event_name": "add_to_cart", "created_at": "2026-08-04 00:14:59", "params": { "item_id": "SKU_98765", "price": 299.99 } } ] }

GET/api/v1/projects/{channelid}/segments

プロジェクトに定義された訪問者セグメントを一覧表示します（プロジェクト固有とワークスペース全体の両方）。

{ "data": [ { "segment_id": 4, "name": "High Intent Visitors", "description": "Pageviews > 5", "badge_color": "cyan", "is_global": 0, "created_at": "2026-08-03 00:00:43" } ] }

5. バックエンドから顧客 ID を付加する

ブラウザーは、操作している人が誰かを知らないことがよくあります。B2B 製品ならログイン後、バックエンドで身元が確定します — ショップなら注文確認時です。このエンドポイントは、まさにその瞬間のためにあります。

POST /api/v1/sessions/{session_id}/identify
Authorization: Bearer mp_live_xxxxxxxxxxxx
Content-Type: application/json

{"user_id": "customer-4711"}

// 200 OK
{"data": {"session_id": "s_a1b2c3", "user_id": "customer-4711",
          "changed": true, "previous": null, "webhook_queued": true}}

ID はセッション一覧に表示され、検索できるようになります。また、 session_identified Webhook が発火します — これが CRM に届く経路です。

同じ ID で2回呼び出しても安全です。 レスポンスには次が含まれ、 "changed": false Webhook は送信しません。注文が繰り返されても、二つ目の見込み客は作られません。

ステータス	条件
`400`	フィールドがない、 `user_id` 128文字超、または制御文字を含む場合。切り詰めずに拒否します — 通知なく短縮した ID は、CRM の何とも一致しないのに、成功に見えてしまうためです。
`404`	セッションが存在しない、またはお客様のワークスペースに所属しない場合。意図的に両方で同じ応答を返します。
`403`	ワークスペースのプランに API が含まれない場合。

6. Webhook：署名の検証

Webhook は、プロジェクトごとに連携で設定します。署名用シークレットも同じ場所にあります。各配信には、次のヘッダーが含まれます。

ヘッダー	意味
`X-MousePlayer-Event`	イベント名。例： `session_identified`
`X-MousePlayer-Timestamp`	Unix 秒 — 署名対象テキストの一部
`X-MousePlayer-Attempt`	初回は1、再試行では増加
`X-MousePlayer-Signature`	`sha256=<hex>`

署名は、次に対する HMAC-SHA256 です： timestamp + "." + raw body。プロジェクトの署名用シークレットをキーに使います。

// PHP
$erwartet = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($erwartet, $signature)) { http_response_code(401); exit; }

// Node
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
                                     .update(timestamp + '.' + rawBody).digest('hex');

JSON の解析を行う前に、生の本文を署名対象にしてください。再シリアライズするとキーの順序や空白が変わり、署名は一致しなくなります。また、タイムスタンプが数分以上古いものは拒否してください — タイムスタンプはそのためにあります。

配信と再試行

配信に失敗した場合、次の間隔で再試行します： 1分、5分、15分、1時間、6時間。その後は打ち切ります。 4xx レスポンスが、次の 408 と 429 以外の 場合は再試行しません — それらは "今はだめ" ではなく "この方法ではだめ" を意味するためです。次を速やかに返し、 2xx 作業は後で行ってください。配信は10秒でタイムアウトします。

利用可能なイベント

イベント	発火条件
`session_identified`	セッションに初めて顧客 ID が付いたとき — ブラウザーまたは API から
`session_ended`	セッションが終了したときに1回
`goal_reached`	カスタムイベントが目標の一つを満たしたとき、セッションごとに1回。対象は「event」型の目標のみ — URL、滞在時間、ページビュー、ファネルの目標は評価しません。含まれるもの： `goal_id`、 `goal_name`、 `goal_value` と `currency`。
`high_value_session`	ある日に訪問者が、このプロジェクトの価値しきい値を初めて超えたとき。しきい値は、お客様自身のスコア分布から導出します（直近90日間の90パーセンタイル）。固定値ではなく、20人以上の訪問者にスコアが付くまでは存在しません。含まれるもの： `visitor_id`、 `value_score`、 `threshold` および、その日の最も視聴に適したセッション。
`funnel_dropoff`	ファネルの一つに入ったものの、完了しなかったセッションの終了時。停止したステップ（`dropped_at`）を示します。離脱はイベントの不在であるため、セッション終了後にしか確定できません。ファネルに一度も入っていないセッションは離脱ではなく、発火しません。
`high_friction_session`	セッションごとに1回、フリクションスコアが初めてしきい値（初期値は100中60）に達したとき。含まれるもの： `friction_score`、その背景のシグナル（`reasons`）、しきい値を超えたきっかけのシグナル（`trigger`）。
`element_broken`	追跡対象の要素が、確認したどのページビューでも数日間見つからなかったときに1回 — 通常はリニューアル後に起こります。再度発火するのは、マーキングが一致した後、再び壊れた場合だけです。このイベントが所属するセッションはありません。 `session_id` と `session_url` は、 `null`です。 `link_url` は代わりにマーキングを開き、 `subject_id` はマーキングを識別します — どのバージョンでも同じため、新しいセレクターが再び壊れた場合も、未解決のインシデントに結び付きます。含まれるもの： `rule_id`、 `rule_name`、 `selector`、 `page`、 `checked_page_views`、 `window_days` と `last_matched`。訪問者データは含みません。
`element_recovered`	次の復旧通知です： `element_broken`。マーキングが実際に再び要素を見つけたときに通知します — ページビューが少ないだけでは不十分です。 `element_broken` が Webhook で送信された場合だけ送信します。独自のスイッチはなく、 `element_broken` を購読すると含まれます。同じ `subject_id`を使うため、PagerDuty はインシデントを解決し、Opsgenie はアラートを終了します。さらに、 `matched_page_views` と `checked_page_views` が含まれます。
`anomaly_detected`	1日1回、昨日がその前の28日間と明らかに異なった場合に発火します。セッションの大幅な減少・増加、目標達成率の低下、フリクションや JS エラーを伴うセッションの増加などです。同じ指標・方向の通知は1週間抑制します（調整可能）。このイベントが所属するセッションはありません。 `session_id` と `session_url` は、 `null`です。 `link_url` はプロジェクト概要を開き、 `subject_id` は指標、方向、日付を識別します。含まれるもの： `metric` （`sessions`、 `goal_rate`、 `friction_rate`、 `js_error_rate`、 `lcp_p75`、 `inp_p75`、 `cls_p75`）、 `direction`、 `day`、 `value`、 `expected`、 `sessions`、 `robust_z`、 `z_score` および読みやすい `summary` と `hint`。訪問者データは含みません。Web Vitals の場合、 `measurements` が、次の代わりに使われます： `sessions`。また、 `page` （サイト全体なら空欄）と `device` （`desktop` または `mobil`）が発生場所を示します。 `link_url` は、その場合 Web Vitals タブを開きます。
`rage_click`	連打クリックの検出時
`error_detected`	フロントエンドの例外時
`ce`	お客様独自のカスタムイベントをまとめて購読します。上記のイベントは含みません — それらには独自のスイッチがあります。

7. エラー & ステータスコード

ステータス	意味
`200`	成功。
`401`	API キーがない、不正な形式、または取り消されている。
`404`	要求したプロジェクトまたはセッションが存在しない、またはお客様のワークスペースに所属しない。
`429`	レート制限の超過 — このキーで1分間に60リクエストを超えて送信している。
`403`	ワークスペースのプランに REST API が含まれない。メッセージに、必要なプランと現在のプランの両方を示します。

8. セキュリティ上の注意

読み取り専用キー（mp_ro_）では何も変更できません。書き込みキー（mp_rw_）で行えるのは、顧客 ID の付加だけです。データの削除や生の再生データのエクスポートは、どのキーでもできません。
すべてのリクエストは自動的にキー自身のワークスペースに限定されます — 別のワークスペース ID を渡して他の人のデータを見る方法はありません。
次からいつでもキーを取り消せます： /api-keys。取り消しは直ちに有効になります。
API キーはパスワードと同じように扱ってください。誤って公開リポジトリにコミットした場合は、直ちに取り消し、新しいキーを作成してください。

件数を制限したイベントページ（API v1、2026年10月14日）

GET /api/v1/sessions/{session_id}/events は、初期設定で最大100イベントを返します。per_page は1から100までの整数に設定します。pagination.next_cursor に従い、次のリクエストで cursor を変更せず送信し、同じセッションとワークスペースを維持してください。イベントは created_at と event_id の順です。カーソルには署名が付き、そのセッションとワークスペースに結び付けられます。総件数や数値のページ番号は返しません。

既存の data 配列と params マップは引き続き利用できます。pagination.returned は実際に返された件数、pagination.has_more は次のページの有無です。完了時は next_cursor が null になります。レスポンスの上限は524288バイトなので、ページに含まれるイベントが per_page より少なくなる場合があります。イベントごとに返すパラメーター行は最大128行です。それ以上ある場合は params_truncated が true になります。個々の文字列パラメーターには、データベースの255文字制限が引き続き適用されます。切り捨てられたパラメーターは、このエンドポイントでは取得できません。per_page を小さくしても、パラメーター数の上限は増えません。

不正なページサイズ、変更されたカーソル、別のセッション／ワークスペースのカーソルには400を返します。個別のイベントデータが大きすぎる場合は413を返します。既存のアクセス確認も、状況に応じて引き続き401、403、404、409を返します。

上限は引き続き、API キーごとに1分間で60件の認証済みリクエストです。超過時は429と Retry-After: 60 を返します。Redis またはレート制限機能が利用できない場合、リクエストには503と Retry-After: 5 を返し、制限なしに受け入れることはありません。Retry-After に従い、ランダムな待機時間を加えてください。短いループで再試行しないでください。イベントデータベースの障害でも503を返します。カーソルはスナップショットを固定しません。古いタイムスタンプを持つ行が同時に挿入された場合、最初からの再走査が必要になることがあります。

GET /api/v1/sessions/s_example/events?per_page=25
GET /api/v1/sessions/s_example/events?per_page=25&cursor=SIGNED_CURSOR

/api/v1/native は、ネイティブ SDK プレビュー用の Dev 専用バックエンド制御ルートです。本番環境では引き続き無効です。バックエンドの Bearer キーには、list/replay で読み取り範囲、register/grant/delete/disable で書き込み範囲が必要です。ネイティブプレビューの利用可否について追加の確認も適用されます。永続的なワークスペース API キーをモバイルアプリに埋め込むことは絶対にしないでください。

どのようなことでお困りですか？