consuming-endpoints-from-client-code

クライアントコードからエンドポイントを呼び出す

このスキルは、creating-an-endpoint に対する呼び出し側のスキルです。既存のエンドポイントを別のコードベース（モバイルアプリ、サーバーバックエンド、顧客向けダッシュボード、下流のパイプラインなど）に統合する方法を説明します。ここでは PostHog のコードは変更しません。

このスキルを使う場面

• 「エンドポイントの呼び出し方を教えて」／「リクエストはどのような形式ですか？」
• 「このエンドポイント用に、型付きの TypeScript／Python／Go クライアントを生成して」
• 「エンドポイントを呼び出すと 401 が返されます」／認証に関する質問
• 「user_id を省略するとエンドポイントにリクエストを拒否されます」→ materialised-endpoint の変数に関する質問
• 「レート制限にはどう対処すればよいですか？」

ユーザーがエンドポイントを作成している場合は、先に creating-an-endpoint を使ってください。

利用可能なツール

ツール	用途
endpoint-get	名前を指定したエンドポイントの完全な設定。クエリの形状と必須変数を含みます
endpoint-openapi-spec	エンドポイント 1 つ分の OpenAPI 3.0 仕様。コードジェネレーターにそのまま渡せます
endpoint-run	エンドポイントへのライブ呼び出し。ユーザーのアプリと共有する前に、ペイロードが機能するか確認するのに便利です

エンドポイントの URL

/api/projects/{team_id}/endpoints/{name}/run

• team_id はプロジェクト ID（数値）です。PostHog のプロジェクト設定で確認するか、ユーザーが分からない場合は projects-get で取得できます。
• name はエンドポイント名です。ユーザーが分からない場合は endpoints-get-all を確認してください。
• 末尾の /run は必須です。

標準のメソッドは POST です。リクエストボディが不要な単純なケースでは GET も使用できますが、変数をボディに含めるため、POST を推奨します。

認証

エンドポイントの認証には個人用 API キーを使います。ヘッダーは次のとおりです。

Authorization: Bearer <key>

キーにはスコープが設定されています。エンドポイントの場合、少なくとも endpoint:read が必要です。403 が返される場合は、通常、必要なスコープが不足しています。401 が返される場合は、キーがないか、形式に誤りがあります。

エンドユーザーに配布するクライアントサイドコード（モバイルアプリやブラウザーの JavaScript など）に個人用 API キーを含めないでください。個人用 API キーを使うと、スコープで制限されたアカウントへのアクセスが可能になります。顧客向けアプリでは、キーを保持するユーザー自身のバックエンドを経由してください。

リクエストペイロード

{
  "variables": { "code_name_1": value, "code_name_2": value },
  "limit": 100,
  "offset": 0,
  "refresh": "cache"
}

フィールド	説明
variables	HogQL エンドポイントでは code_name をキーにします。ブレークダウンを含むインサイトエンドポイントでは、ブレークダウンのプロパティ名をキーにします
limit	返される最大行数。
offset	スキップする行数。HogQL エンドポイントのみ
refresh	"cache"（十分に新しいキャッシュ結果を返す）、"force"（常に再計算する）、"direct"（マテリアライズをバイパスする。マテリアライズ済みエンドポイントのみ）。デフォルトは "cache" です

変数の正確な形式を確認するには endpoint-get を呼び出してください。レスポンスには、宣言済みの変数を含むクエリ定義が含まれます。各変数の code_name が、クライアントから送信する値です。

マテリアライズされたエンドポイント：すべての変数が必須です

現在のバージョンで endpoint-get に is_materialized: true と表示される場合、エンドポイントを呼び出すたびに、宣言されているすべての変数を渡す必要があります。これはセキュリティ境界です。フィルターがないと、1 回の呼び出しで事前集計されたデータセット全体が返されてしまいます。

よくある症状：エンドポイントがマテリアライズされていないときはユーザーのアプリで正常に動作していたのに、マテリアライズを有効にした後から 400 エラーが返されるようになります。エラーメッセージには、不足している変数が列挙されます。

マテリアライズされたエンドポイントで変数を任意指定または一部だけ指定できないことは既知の制限であり、PostHog チームは解消を予定しています。すべての変数を必須にすることでユーザーのユースケースに支障が出る場合は、agent-feedback ツールからお知らせください。その要望が、チームの優先順位付けに役立ちます。

型付きクライアントの生成

エンドポイントは、endpoint-openapi-spec を通じて専用の OpenAPI 3.0 仕様を公開します。それをコードジェネレーターに渡してください。

言語	ツール	コマンドの形式
TypeScript	@hey-api/openapi-ts	openapi-ts -i spec.json -o ./generated
TypeScript	openapi-generator-cli	openapi-generator-cli generate -i spec.json -g typescript-fetch -o ./generated
Python	openapi-generator-cli	openapi-generator-cli generate -i spec.json -g python -o ./generated
Go	oapi-codegen	oapi-codegen -package=client spec.json > client.go

生成されたクライアントを使うと、変数のペイロードとレスポンスの形式に対応する型を利用できます。エンドポイントのクエリを変更したら、再生成してください（新しいバージョンでは変数が異なる場合があります）。

エンドポイントが複数ある場合は、エンドポイントごとに仕様を生成し、それらを統合するか、エンドポイントごとにクライアントを生成して併用してください。

レスポンスの形式

一般的な成功時のレスポンス：

{
  "results": [[...], [...]],
  "columns": ["col_a", "col_b"],
  "types": ["Int64", "String"],
  "hasMore": false,
  "name": "endpoint_name",
  "endpoint_version": 4,
  "endpoint_version_created_at": "2026-01-15T..."
}

• results は行の配列です。各行は、columns の順序に対応するセル値の配列です。
• endpoint_version は、実際に実行されたバージョンをクライアントに伝えます。ログ記録や、?version=N を使って既知のバージョンに固定する際に役立ちます。

Insight エンドポイントでは、レスポンスの形式はクエリの種類（TrendsQuery、LifecycleQuery、RetentionQuery）によって異なります。OpenAPI 仕様には、現在のバージョンに適した形式が記載されています。マテリアライズできない Insight の種類（例：FunnelsQuery）でも、インラインの結果形式が返されます。

PostHog CLI からの呼び出し

ローカルテスト、スクリプト、CI では、リポジトリの posthog-cli を使うと、HTTP 呼び出しを自分で実装せずにエンドポイントを呼び出せます。

• posthog-cli exp endpoints run — エンドポイントを実行します（ローカルの YAML 定義を使用）。
• posthog-cli exp endpoints {list,get,pull,push,diff} — エンドポイントを調べるか、バージョン管理下の YAML ファイルとして管理します（GitOps スタイル）。

認証には、posthog-cli login または POSTHOG_CLI_API_KEY / POSTHOG_CLI_PROJECT_ID / POSTHOG_CLI_HOST 環境変数を使って、同じ個人用 API キーを使用します。（これらの機能は exp 配下にあり、実験的なため変更される可能性があります。）

対応が必要なエラーレスポンス

ステータス	発生条件	対応
400	マテリアライズされたエンドポイントで必須変数が指定されていない、または変数の型が無効	エラーメッセージを表示し、呼び出しを修正します
401	個人 API キーが未指定、または誤っている	Authorization ヘッダーを確認します
403	キーに endpoint:read スコープがない、またはエンドポイントが別のプロジェクトにある	キーのスコープを調整します
404	エンドポイント名の入力ミス、またはエンドポイントが有効でない	名前を確認し、is_active を確認します
429	レート制限 — 制限はエンドポイントごとではなくチームごとに適用されます（下記の注記を参照）	指数バックオフを行います。可能であればクライアント側でレスポンスをキャッシュします
5xx	クエリ実行エラー（ClickHouse エラー、タイムアウトなど）	バックオフを行って再試行します。解消しない場合は diagnosing-endpoint-performance に引き継ぎます

ワークフロー

1. エンドポイント名を確認します。不明な場合は、system.data_modeling_endpoints に対して execute-sql を実行するか、endpoints-get-all で一覧を取得します。
2. endpoint-get で変数、マテリアライズの状態、クエリの種類など、全体の構造を確認します。
3. 認証方法を決めます。サーバー上では個人 API キーを使用し、クライアント側では決して使用しないでください。
4. ユーザーが生成型を求めている場合は、endpoint-openapi-spec を呼び出して仕様を渡し、使用言語に対応するジェネレーターを推奨します。
5. 変数の宣言に基づいてリクエストのサンプルペイロードを作成し、テスト呼び出しの手順を説明します。
6. 必要に応じて、このスキルから endpoint-run を呼び出し、ペイロードが機能することを確認します。
7. 最後に、マテリアライズされた変数のルール、レート制限の仕組み、?version=N によるバージョンの固定について説明します。

対話例

User: "I want to call monthly_active_users from my Node.js backend.
       Can you help me wire it up with types?"

Agent steps:
- endpoint-get monthly_active_users → HogQL, variables: lookback_days
  (int, default 30), org_id (string, no default), is_materialized: true
- "Two things to know upfront:
   1. This endpoint is materialised, so both lookback_days and org_id
      must be passed on every call. Calls without them will be rejected.
   2. You'll need a personal API key with endpoint:read scope. Set it
      as PH_API_KEY in your server env — never ship it in client code."

- endpoint-openapi-spec monthly_active_users → returns spec

- "Here's the spec. Drop it in your repo and run:
     pnpm dlx @hey-api/openapi-ts -i spec.json -o ./generated/posthog
   That gives you typed client functions.

   A minimum call looks like:
     POST /api/projects/12345/endpoints/monthly_active_users/run
     Authorization: Bearer <PH_API_KEY>
     Content-Type: application/json

     { 'variables': { 'org_id': 'acme', 'lookback_days': 30 } }

   The response includes columns and rows — your client will pick that
   up from the generated types.

   Want me to do a sample call to verify the payload works?"

重要な注意事項

• 個人の API キーはサーバー側でのみ使用してください。 モバイルアプリやブラウザーの JavaScript に含めないでください。
• クエリを変更したら、クライアントを再生成してください。 エンドポイントのバージョンが新しくなるたびに、変数が追加または削除されることがあります。仕様を再取得して、型を同期してください。
• マテリアライズ済みのエンドポイントでは、変数が不足している呼び出しは拒否されます。 これは意図的な動作です。マテリアライズを有効にした後にユーザーから 400 エラーの報告があった場合、修正すべきなのはエンドポイントではなく呼び出しです。
• 「latest」に頼らず、バージョンを固定してください。 常に ?version=N を付けて呼び出してください。指定しない場合は、最新のアクティブバージョンが実行されます。そのため、将来クエリを編集して新しいバージョンが作成されると、呼び出し側の結果が予告なく変わることがあります。新しいバージョンを検証してから、意図的に固定バージョンを更新してください。
• クライアント側のキャッシュは自由に追加できます。 エンドポイントはすでに data_freshness_seconds を使ってキャッシュしていますが、頻繁にアクセスされる処理では、クライアント側でさらにキャッシュを重ねることができます。全体のデータの古さ（エンドポイントのキャッシュ＋クライアントのキャッシュ）に注意してください。
• レート制限はエンドポイントごとではなく、カテゴリごとにチーム単位で適用されます。 マテリアライズされていないエンドポイントへの呼び出しは、チーム全体の API クエリの上限（バースト時は約 240 回／分、継続時は約 2400 回／時）を、ほかのすべてのクエリトラフィックと共有します。マテリアライズ済みのエンドポイントは、別の、より大きい共有枠（約 1200 回／分、約 12000 回／時）を使用します。エンドポイント名ごとの制限はないため、1 つのエンドポイントに過剰にアクセスすると、同じチームのほかのエンドポイントにも影響する可能性があります。大量に呼び出す場合は、可能な限りバッチ処理を行い、429 が返されたらリクエストの間隔を空けてください。
• 料金について。 現時点ではエンドポイントの呼び出しに料金はかかりませんが、エンドポイントがマネージドウェアハウスとともに提供されるようになると、料金が発生します。大量利用を計画しているユーザーには、将来的に費用が発生することを事前に伝えてください。
• 不足している点を PostHog に伝えてください。 エラー、制限、機能不足が妨げになった場合は、agent-feedback ツールを使用してください。これは、チームがエンドポイントとこれらのツールを改善するための主なフィードバック手段です。