creating-an-endpoint

エンドポイントの作成

このスキルでは、適切な設定で新しいエンドポイントを作成する方法を説明します。エンドポイントを使うと、保存済みの HogQL クエリやインサイトクエリを呼び出し可能な HTTP ルートとして公開できます。作成時の設定によって、コストやレイテンシ、呼び出し元との連携方法が決まります。

マテリアライゼーションの詳細については、references/materializing.md を参照してください。マテリアライゼーションの判断が明確でない場合に読み込んでください。

このスキルを使う場面

• 「[query] のエンドポイントを作成して」
• 「このインサイトを API として公開して」
• 「この HogQL を呼び出し可能なエンドポイントにするのを手伝って」
• 新しい呼び出し元（モバイルアプリ、顧客向けダッシュボード、下流のパイプライン）が PostHog のデータを必要としており、ユーザーがデータの提供方法を選んでいる

順番に決めること

1. そもそもエンドポイントにするべきか？

次の場合は、エンドポイントが適しています。

• 外部システム（他者のコード）が、データ取得のために PostHog を呼び出す必要がある
• クエリが安定している（探索的な分析ではない）
• 同じクエリを異なるパラメーターで使うなど、結果の形式が再利用可能である

次の場合は、エンドポイントは適していません。

• 内部の PostHog ダッシュボードやインサイトでデータが必要な場合は、インサイトを直接使ってください。エンドポイントを作成すると、内部では不要な外部 API のインターフェースが追加されるだけです
• 一度限りの探索的な分析の場合は、execute-sql ツール（または SQL エディター）を直接使ってください

集計処理が重いことは、エンドポイントを避ける理由にはなりません。エンドポイント自体が保存済みクエリであり、処理が重く頻繁に呼び出される集計は、マテリアライゼーションを有効にしたエンドポイントが最適なケースであることもよくあります。

ユーザーが判断に迷っている場合は、エンドポイントを呼び出すものと、期待する結果の形式を確認してください。

2. 名前を決める

名前には URL で安全に使える文字（英字、数字、ハイフン、アンダースコア）を使用し、英字で始める必要があります。最大 128 文字で、プロジェクト内で一意でなければなりません。次の点を意識してください。

• 汎用的な名前より具体的な名前 — metrics より weekly_active_users_by_org
• snake_case — コードパスや URL に表示される名前と一致します
• 名前にバージョンを含めない — バージョンはエンドポイント自体で管理します
• 名前に「endpoint」を含めない — 冗長です

名前は URL に表示されます：/api/projects/{team_id}/endpoints/{name}/run。後から簡単に名前を変更することはできません（呼び出し元がパスに依存するため）。作成時に適切な名前を付けてください。

3. クエリの種類を選ぶ

次の 2 つの選択肢があります。

• HogQL（HogQLQuery） — ユーザーが記述する生の SQL です。変数は {variables.x} 構文で定義し、code_name によって照合します。呼び出し元がレスポンスの列構成を正確に把握する必要がある新しいエンドポイントでは、この方法を推奨します。
• インサイト — 既存のインサイト定義をラップします。最もよくサポートされるのは TrendsQuery、LifecycleQuery、RetentionQuery です。これらはマテリアライズでき、ブレークダウンを変数として使えます（Trends と Retention のみ。Lifecycle にはブレークダウンがありません）。FunnelsQuery など、その他のインサイトの種類はインラインで実行できますが、マテリアライズできず、ブレークダウン変数も公開されません。どちらかが必要な場合は、HogQL で書き直してください。

HogQL の方が柔軟です。新しいクエリを作成するのではなく、ユーザーが既存のインサイトを本当に再公開したい場合に限り、「既存のインサイトから作成する」を参照してインサイトを選んでください。

4. どの入力を変数にするかを決めます

呼び出し元ごとに変更する必要があるものは変数にし、それ以外はクエリにハードコードします。

HogQL エンドポイントの場合、クエリペイロードで code_name、type、 default を使って変数を宣言します。各実行呼び出しでは { "variables": { "<code_name>": value } } を渡します。

よくあるパターン：

• 時間範囲：date_from、date_to、または単一の lookback_days 整数
• ID フィルター：user_id、account_id、team_id
• limit／offset 以外のページネーション制御（これらは実行エンドポイントですでに標準でサポートされています）

インサイトエンドポイントの場合、ブレークダウンプロパティが変数として機能します（Trends と Retention のみ。Lifecycle にはブレークダウンがありません）。ブレークダウンプロパティ名をキーとして渡します。date_from／ date_to は、マテリアライズされていないインサイトエンドポイントでのみ変数として指定できます。マテリアライズされたエンドポイントでは日付範囲がビューに組み込まれるため、呼び出し元は期間を変更できません。

次のことは避けてください：

• 結果の形を変える変数 — 列は固定してください。呼び出し元が根本的に異なる結果の形を必要とする場合は、エンドポイントを分けてください。
• 安全性を損なう変数 — 呼び出し元が任意の SQL を挿入できる where_clause 変数は公開しないでください。

既存のインサイトから作成する

サーバー側には「インサイト N からエンドポイントを作成する」操作はありません。作成するには、インサイトのクエリを（インサイトツールを使って）読み取り、そのクエリを endpoint-create に渡し、derived_from_insight にインサイトの短縮 ID を設定して、作成元が記録されるようにします。エンドポイントはクエリのコピーを独自に保持するため、後でインサイトを編集しても反映されません。最初から作成する場合は、先にインサイト／sql-variables ツールを使ってクエリを作成してから、そのクエリを基にエンドポイントを作成します。

5. data_freshness_seconds を設定する

このフィールドは2 つの役割を持つため、意図的に設定してください。

1. キャッシュ TTL — 結果は、この秒数が経過するまでキャッシュから提供されます。
2. マテリアライズの更新頻度 — マテリアライズされたエンドポイントでは、データウェアハウスがマテリアライズドビューを再計算する頻度もこの値で決まります。

つまり、値を小さくするとデータの鮮度が上がる一方、再計算／更新のコストも増えます。値を大きくすると、どちらのコストも抑えられますが、データは古くなります。

指定できる値は固定された次のいずれかです：900（15 分）、1800（30 分）、3600（1 時間）、21600 （6 時間）、43200（12 時間）、86400（24 時間、デフォルト）、604800（7 日）。15 分未満の 設定はできません。最小値は 900 です。

data_freshness_seconds	選択する場面
900–1800	利用可能な範囲で最も新鮮なデータ — 古さが目立つダッシュボード
3600–43200	ほとんどの場合 — プロダクトの利用状況を把握するには十分新鮮で、再計算コストも低い
86400–604800	レポート、週次／日次メトリクス、長期間の集計データを扱う場合

ユーザーがより新鮮なデータを明示的に必要としていない限り、大きめの値を優先してください。マテリアライズされたエンドポイントでは、これが更新間隔も設定することを忘れないでください。

6. 初日からマテリアライズするかを決める

判断基準の全体については references/materializing.md を参照してください。要点は次のとおりです。

• マテリアライズを推奨する場合：エンドポイントが頻繁に呼び出され、レイテンシが重要で、更新間隔に相当するデータの古さを許容できる場合（通常、スケジュールされたマテリアライズでは 5～15 分、または 1 時間）。
• マテリアライズを見送る場合：トラフィックの少ないエンドポイント、新規の探索的なエンドポイント（呼び出されるかどうかまだわからない場合）、鮮度が重要なクエリ。

判断に迷ったら、まずはマテリアライズせずに作成し、利用状況が安定してから is_materialized: true を追加してください。これなら、結局誰にも使われないクエリのマテリアライズに費用をかけずに済みます。

ワークフロー

1. ユースケースを確認します（上記のステップ 1）。エンドポイントに適さない場合は、代替案を提案します。
2. ユーザーと名前を決めます。
3. クエリを確認します。HogQL またはインサイトのどちらか、列や形式が適切かを確認します。
4. 変数にすべきものを特定します。変数の宣言構文をユーザーに示します。
5. ユーザーのデータ鮮度の要件に基づいて data_freshness_seconds を選びます（明確でない場合は尋ねます）。これによってマテリアライズの更新頻度も設定されることを忘れないでください。
6. マテリアライズを実行します。判断に迷う場合は、マテリアライズせずにリリースし、後で見直します。
7. 合意した設定で endpoint-create を呼び出します。
8. サンプルペイロードを使って endpoint-run を呼び出し、レスポンスの形式を確認します。
9. ユーザーが接続を実装しようとしている場合は、consuming-endpoints-from-client-code に引き継ぎます。

対話例

User: "I want to expose our monthly active users count as an API
       for our analytics partner"

Agent:
- "Quick check: is the partner going to call this on demand, or
   should we be pushing data to them? Endpoints are pull-only."
- User: "On demand"
- "Got it. A few choices:
   - Name: how about monthly_active_users? Lowercase, descriptive,
     no version baggage.
   - The query — is it HogQL or are you exposing an existing insight?
     HogQL gives you exact column control; insight reuses what you've
     already built.
   - What should the partner be able to filter by? Org, time window,
     both?
   - How fresh? If MAU drifts within a day is fine, we can cache
     results for 1-24 hours and serve almost everything from cache.
   - Materialisation: if the partner is going to hit this many times
     per day, materialising it would make responses near-instant.
     The trade-off is ~10-15 minute staleness.

   What's your starting point on these?"

[user picks: HogQL, lookback_days + org_id variables, 3600s TTL,
 not materialised yet]

- endpoint-create monthly_active_users {query, variables, ...}
- endpoint-run with sample payload {org_id: "test", lookback_days: 30}
- "Created and tested. Want help wiring up the client code?
   That's consuming-endpoints-from-client-code."

重要な注意事項

• 名前は URL に含まれます。 後から変更するには、呼び出し元の移行が必要です。慎重に選んでください。
• HogQL エンドポイントはインサイトエンドポイントより柔軟です。 既存のインサイトをラップする明確な理由がない限り、HogQL を選んでください。
• デフォルト値のない変数は、呼び出し時にエラーになります。 すべての変数のデフォルト値を作成時に設定し、すべての変数を指定せずにプレイグラウンドからエンドポイントをテストできるようにしてください。
• マテリアライズされたエンドポイントでは、すべての変数を渡す必要があります。 変数なしの呼び出しは拒否されます。これは意図的な仕様です（セキュリティ上、フィルターされていないデータが返されるのを防ぎます）。マテリアライズを提案する際は、必須になる変数についてユーザーに伝えてください。 （マテリアライズされたエンドポイントでの変数の任意指定や一部指定は既知の制限事項で、PostHog チームは解消を予定しています。これがユーザーの妨げになる場合は、agent-feedback ツールを使ってフィードバックを送ってください。）
• 適格でないクエリではマテリアライズを有効にしないでください。 まず endpoints-materialization-preview を使って適格性を確認し、該当する場合は拒否理由を確認してください。
• エンドポイントは永久に安定しているわけではありません。 ユーザーがクエリを変更すると、新しいバージョンが自動的に作成されます（古いバージョンには ?version=N で引き続きアクセスできます）。data_freshness_seconds とマテリアライズの設定はバージョンごとに適用されます。エンドポイントの変更に応じて調整してください。
• 呼び出し元にはバージョンを固定するよう勧めてください。 「最新」に頼るのではなく、?version=N を付けて呼び出すようユーザーに伝えてください。こうすれば、将来クエリが編集されて新しいバージョンが作成されても、結果が予期せず変わることはありません。新しいバージョンを検証した後、意図的に固定バージョンを更新できます。
• 不便な点は agent-feedback で共有してください。 制限事項（適格性のルール、必須変数、TTL の列挙値など）が妨げになる場合は、PostHog チームに知らせてください。そうすることで、プロダクトとこれらのツールが改善されます。