copying-endpoints-across-projects

プロジェクト間でエンドポイントをコピーする

このスキルでは、PostHog の エンドポイント（呼び出し可能な API ルートとして公開された、保存済みの HogQL クエリまたはインサイトクエリ）を、同じ組織内の別のプロジェクト、または同じプロジェクト内の新しい名前で複製します。

最初に知っておくべきこと

サーバー側にエンドポイントのコピー操作はありません。 フィーチャーフラグには feature-flags-copy-flags-create、実験には experiment-copy-to-project がありますが、エンドポイントにはどちらもありません。エンドポイントのコピーとは、次の操作を意味します。

1. endpoint-get でソースの設定全体を読み取ります。
2. endpoint-create で再作成します（対象プロジェクト、または同じプロジェクト内の新しい名前で）。

endpoint-get と endpoint-create はどちらもアクティブな MCP プロジェクトのみを対象としており、どちらにもプロジェクト ID を指定できません。そのため、プロジェクト間でコピーするには、読み取り（ソース）と書き込み（対象）の間でアクティブなプロジェクトを切り替える必要があります。まずソースを読み取って設定を保存し、その後、対象に切り替えて作成してください。このセッションでプロジェクトを切り替えられない場合は、誤ったプロジェクトにコピーを作成せず、その旨をユーザーに伝えてください。

このスキルを使う場面

• 「このエンドポイントを別のプロジェクトにコピーして」「このエンドポイントを複製して」「エンドポイントをクローンして」
• 「エンドポイントをステージングから本番環境に昇格して」（環境としてのプロジェクト）
• 「稼働中のものに触れずに試せるよう、コピーを作って」（同じプロジェクト内で新しい名前を付けて複製）
• 別のワークスペースで、エンドポイントのクエリ、変数、鮮度設定を再現する

このスキルで扱わないこと

• 組織をまたいだコピー。 エンドポイント（およびそのクエリ）は、編集者アクセス権のあるプロジェクトでのみ再作成できます。組織間でコピーする方法はありません。
• 既存のエンドポイントのバージョン編集 — managing-endpoint-versions を参照してください。
• 新しいエンドポイントをゼロから設計すること — creating-an-endpoint を参照してください（このスキルでは、ソースのエンドポイントがすでに存在し、正しく設定されていることを前提とします）。
• プロジェクト内の全エンドポイントの一括コピー。 1 つずつコピーしてください。ユーザーが本当にすべてを希望する場合は、endpoints-get-all → エンドポイントごとのコピーを繰り返し、その旨を伝えてください。

ワークフロー

1. ソースのエンドポイントを特定する

エンドポイントの名前とソースプロジェクトが必要です。

• ユーザーが名前を指定した場合は、その名前を使用します。あいまいな説明の場合は、ソースプロジェクトで endpoints-get-all を呼び出し、名前または説明を照合します。
• エンドポイントがどのプロジェクトにあるかユーザーが指定していない場合は、確認してください。アクティブな MCP プロジェクトがソースだと決めつけてはいけません。誤ったソースからコピーすることは、最もよくある失敗です。
• 読み取りの前に、project-get を ID なしで呼び出してアクティブなプロジェクトを確認し、それがソースであることを確かめてください。

2. ソースの設定全体を読み取る

ソース名を指定して endpoint-get を呼び出します。再作成に必要な情報をすべて保存します。

• name
• query（宣言済みの変数や code_name を含む、HogQL クエリまたはインサイトクエリの定義全体）
• description
• data_freshness_seconds
• is_materialized（ソースの状態。通常はそのままコピーしない理由については、手順 5 を参照してください）
• tags

コピーの前に、クエリが返す内容、変数、鮮度設定、ソースがマテリアライズされているかどうかを簡潔にまとめてユーザーに提示します。

3. 対象を特定し、名前の重複を確認する

プロジェクト間の場合： 対象プロジェクトが同じ組織に属しており、ユーザーがそのプロジェクトで編集権限を持っていることを確認します。コピーは endpoint-create の実行時にアクティブになっているプロジェクトに作成されるため、手順 2 と手順 6 の間にアクティブなプロジェクトを対象プロジェクトに切り替えるよう計画してください。

同一プロジェクト内で複製する場合： 新しいエンドポイントには別の名前が必要です。プロジェクト内では名前が一意であり、URL パス（/api/projects/{team_id}/endpoints/{name}/run）はその名前に依存します。ユーザーと新しい名前を決めてください。

どちらの場合も、対象プロジェクトで endpoints-get-all を実行し、指定する名前がすでに存在するか確認してください。存在する場合は中断して確認を求めます。既存の名前を使って作成することを、確認なしで安全に実行することはできません。名前は最初に正しく決めてください。呼び出し側の URL に組み込まれ、後から簡単には変更できません。

4. 対象プロジェクトで名前を決める

• プロジェクト間で目的が同じ場合：呼び出し側のコードを変更せずに移行できるよう、同じ名前を維持します。
• 同一プロジェクト内で複製する場合、または「コピーして反復開発する」場合：元の名前から派生したことが明確な名前を選びます（例：weekly_active_users_v2、weekly_active_users_staging）。snake_case で URL に使用でき、英字で始まり、128 文字以内にしてください。

5. コピーのマテリアライズ設定を選ぶ（デフォルト：OFF）

元がマテリアライズ済みでも、コピーではデフォルトで is_materialized: false にします。 理由は copying-flags-across-projects の安全なデフォルト（無効状態で引き渡す）と同様です。マテリアライズには定期的な再計算とストレージのコストがかかり、コピーしたばかりのエンドポイントは対象プロジェクトでの利用実績がありません。まずはマテリアライズせずに公開し、実際に呼び出されることを確認してから、利用状況に応じて有効にしてください。

ユーザーが最初からマテリアライズした状態でコピーすることを明示的に希望する場合に限り（例：トラフィックの多いエンドポイントを本番環境へ同等の状態で昇格する場合）、is_materialized: true に変更します。creating-an-endpoint に記載された注意点にも留意してください。コホート別の内訳や比較モードを含むクエリ、および Trends／Lifecycle／Retention 以外のインサイト種別（例：Funnels）はマテリアライズできません。endpoint-create を実行しても、これらはマテリアライズされない状態で作成されます。

ユーザーが対象プロジェクトで異なる鮮度を希望しない限り、data_freshness_seconds は元の値をそのまま引き継ぎます（マテリアライズの更新間隔も兼ねていることに注意してください）。

6. コピーを作成する

対象プロジェクトをアクティブにした状態で、以下を指定して endpoint-create を呼び出します。

• name — 手順 4 で決めた名前
• query — 手順 2 で取得した元のクエリをそのまま使用します（変数／code_names も引き継がれます）。
• description — 元の説明（必要に応じてコピーであることを記載します）
• data_freshness_seconds — ユーザーが変更を希望しない限り、元の値
• is_materialized — 手順 5 で決めた値（デフォルトは false）
• tags — ユーザーが希望する場合は元のタグを使用します。対象プロジェクトで意味をなさないタグは削除してください。

7. 検証する

新しいエンドポイントに対して、代表的な variables ペイロードを指定して endpoint-run を呼び出し、レスポンスの形式が元のエンドポイントと一致することを確認します。プロジェクト間で昇格する場合は、クエリが参照するイベント／プロパティが対象プロジェクトに実在することも確認してください。ステージング環境では有効なクエリでも、分類体系の異なるプロジェクトでは結果が空になったり、エラーになったりすることがあります。コピーが HogQL で、呼び出し側が offset ページネーションに依存している場合は、endpoint-run の offset がサポートされるのは HogQL エンドポイントのみであり、インサイトエンドポイントではサポートされないことを伝えてください。

8. 結果を報告する

新しいエンドポイントの名前とプロジェクト、マテリアライズの状態、鮮度の設定、検証実行の結果をユーザーに伝えます。コピーのためにアクティブなプロジェクトを切り替えた場合は、次の呼び出しでユーザーが戸惑わないよう、現在アクティブなプロジェクトも伝えてください。

重要な注意事項

• クエリはリンクではなくコピーです。 インサイトからエンドポイントを作成する場合と同様に、コピー先のエンドポイントはクエリの独自のコピーを保持します。後からコピー元のエンドポイントを編集しても、コピーには反映されません。
• 変数はqueryの中に含まれます。 HogQL のcode_name変数宣言とインサイトのブレークダウン変数はクエリ定義の中にあるため、queryをそのままコピーすれば保持されます。検証実行で、コピー先の変数を必ず確認してください。
• 元に戻せません。 endpoint-createは新しいエンドポイントを作成します（名前がすでに使われている場合は失敗します）。特にコピー先が本番環境の場合は、作成前に必ずユーザーにコピー先の名前とプロジェクトを確認してください。
• アクセス権限。 ユーザーにはコピー先プロジェクトのチームで編集者権限が必要です。権限がない場合、endpoint-createは拒否されます。

利用可能なツール

• endpoint-get — コピー元エンドポイントの設定全体（クエリ、変数、鮮度、マテリアライゼーション、タグ）を読み取ります。?version=Nに対応しています。
• endpoint-create — アクティブなプロジェクトにコピーを作成します。フィールド：name、query、description、data_freshness_seconds、is_materialized、tags。
• endpoints-get-all — アクティブなプロジェクト内のエンドポイントを一覧表示します。曖昧なコピー元の名前の特定や、コピー先での名前の重複確認に使用します。
• endpoint-run — 新しいエンドポイントを実行し、コピーのレスポンス形式を検証します。
• project-get — ID を指定せずに呼び出し、コピー元を読み取る前、またはコピーを作成する前に、現在どのプロジェクトがアクティブかを確認します。