downloading-batch-export-files

バッチエクスポートファイルのダウンロード

ユーザーがPostHogデータを一度だけダウンロード可能な形式でエクスポートしたい場合に、このスキルを使用します。 エクスポートの開始と進捗確認にはMCPを使用しますが、最終ファイルのダウンロードには既存のRESTエンドポイントを直接使用します。

利用可能なMCPツール

ツール	目的
posthog:file-download-batch-exports-create	オンデマンドのエクスポートを開始し、実行IDを返します
posthog:file-download-batch-exports-retrieve	実行ステータスを確認し、完了後にファイルIDを返します

/download/エンドポイントに、生成されたMCPツールを使用しないでください。 このエンドポイントはリダイレクトするファイルダウンロードエンドポイントなので、MCPが明示的なリダイレクトに対応するまでは、生のHTTP／ダウンロード処理が適切なインターフェースです。

ワークフロー

1. エクスポートの形式を選択する

ユーザーが必要な入力項目を指定していない場合は、簡潔な確認質問をします。

• model：events、persons、sessions、hogqlのいずれか
• data_interval_startとdata_interval_end：ISO 8601形式の日時。指定する境界値は、いずれも未来の日時にできません。両方の境界値を指定する場合は、順序が正しく、期間が1週間以内である必要があります
  events、persons、sessionsでは必須です。
  hogqlでは、クエリが参照するプレースホルダーに対してのみ必須です。片方のプレースホルダーしか参照しない場合は、もう片方の境界値を省略でき、1週間の上限も適用されません。
• file.format：ParquetまたはJSONLines。コンパクトな分析用エクスポートにはParquetを、行単位のテキスト処理にはJSONLinesを優先します
• file.compression：任意。zstd、gzip、brotli、lz4、snappyのいずれか。形式にJSONLinesを選択した場合、サポートされるのはgzipとbrotliのみです。
• file.max_size_mb：パートのサイズ（MiB）。デフォルトは1024です。パートのサイズは、この値を少し超えることがあります。
  ユーザーがより小さなパートを希望する場合は値を下げ、より少数の大きなパートを希望する場合は値を上げます。または、サイズを問わず単一ファイルに書き込むにはnullに設定します。

eventsでは、includeとexcludeは任意のイベント名フィルターです。 ユーザーが特定のイベントを指定した場合、または特定のイベントを除外したい場合にのみ使用します。

hogqlでは、クエリをhogql_queryとして渡し、includeとexcludeは省略します。 たとえば、timestampに上限を設けてeventsテーブルの結果を絞り込むなど、HogQLクエリにWHERE句を含めてデータの一部をエクスポートするよう、ユーザーに提案できます。 ユーザーの要望を満たすために必要な最小限のデータだけをエクスポートすることを常に優先してください。 SELECT句のすべての列は、フィールドであるか、エイリアスを持つ必要があります。 このモデルはクローズドベータ版であり、チームごとに有効化されます。

hogqlクエリでは、{data_interval_start}と{data_interval_end}のプレースホルダーを参照できます。 エクスポート時にこれらはdata_interval_startとdata_interval_endの値に置き換えられるため、1つのクエリで任意の期間をエクスポートできます。クエリが参照するすべてのプレースホルダーに対して境界値を指定してください。境界値が不足している場合、リクエストは失敗します。 境界値はプレースホルダーを置き換えるだけで、それ自体で何かをフィルターすることはありません。そのため、プレースホルダーを含まないクエリは、境界値を指定しても変更されずに実行されます。 ユーザーが期間を指定したい場合や、同じクエリから連続した複数の期間をエクスポートしたい場合は、日付を直接指定する代わりにプレースホルダーを優先してください。連続した期間で同じ行を二度エクスポートしないよう、>= {data_interval_start}と< {data_interval_end}で比較してください。

2. エクスポートを開始する

選択した形式でposthog:file-download-batch-exports-createを呼び出します。 レスポンスには、エクスポート実行のidが含まれます。

リクエストの例：

{
  "model": "events",
  "file": {
    "format": "JSONLines",
    "compression": "gzip"
  },
  "include": ["$pageview"],
  "data_interval_start": "2026-05-25T00:00:00Z",
  "data_interval_end": "2026-05-26T00:00:00Z"
}

hogqlモデルのリクエストの例：

{
  "model": "hogql",
  "file": {
    "format": "Parquet"
  },
  "hogql_query": "SELECT event, timestamp, properties.$current_url AS url FROM events WHERE timestamp >= {data_interval_start} AND timestamp < {data_interval_end}",
  "data_interval_start": "2026-05-25T00:00:00Z",
  "data_interval_end": "2026-05-26T00:00:00Z"
}

3. 完了するまでポーリングする

返された id を指定して、posthog:file-download-batch-exports-retrieve を呼び出します。

ステータスの処理：

ステータス	アクション
Starting または Running	少し待ってから再度ポーリングする
Completed	files 配列を読み取り、各ファイルをダウンロードする
Cancelled	停止し、実行がキャンセルされたことを報告する
Failed、FailedRetryable、FailedBilling、Terminated、または TimedOut	停止し、error フィールドの内容を報告する

Completed の場合、files 配列にはファイルの UUID が含まれます。 単一ファイルのエクスポートでは、通常、UUID は 1 つだけです。 分割されたエクスポートでは、ユーザーが特定の一部を指定していない限り、すべての UUID をダウンロードします。

Completed のレスポンスには、エクスポートされた行数である records_completed も含まれます。 各ファイルを開かないと確認できない件数なので、ユーザーに報告してください。

4. 実行中のエクスポートをキャンセルする（任意）

ユーザーが必要とする場合、返された id を指定して posthog:file-download-batch-exports-cancel-create を呼び出すと、実行中のエクスポートをキャンセルできます。

すでに完了または失敗したエクスポートは、キャンセルできない場合があります。

エクスポートをキャンセルした後は、その id を再利用できない場合があり、エクスポートを最初からやり直す必要があります。ただし、エクスポートのステータスの取得には引き続き id を使用でき、そのステータスは常に Cancelled になります。

5. REST 経由でファイルをダウンロードする

既存のエンドポイントに対して、認証済みの HTTP リクエストを直接使用します。

GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/{part}/

part には、次のいずれかを指定できます。

• file-download-batch-exports-retrieve が返す files 配列内のファイル UUID
• キー順に並べた、0 から始まるファイルインデックス

ファイルが 1 つだけの場合は、part を指定しなくても次のように動作します。

GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/

HTTP クライアントにリダイレクトを追跡させるか、一時的な署名付き URL が必要な場合は Location ヘッダーを確認してください。 他の API 呼び出しと同じ PostHog 認証コンテキストを使用してください。

6. ファイルの内容は出力せずに保存する

結果はチャットのレスポンスではなく、ファイルのダウンロードとして扱います。 Parquet はバイナリ形式なので、バイト列として書き込む必要があります。 JSONLines もサイズが大きい場合があるため、ユーザーが少量のサンプルを明示的に求めていない限り、内容を貼り付けずにファイルへ保存してください。

可能であれば、モデル、実行 ID、パート識別子を含むファイル名を使用します。例：

posthog-events-<run_id>-<part>.jsonl.gz
posthog-persons-<run_id>-<part>.parquet

重要な注意事項

• エクスポートの最大期間は1週間です。ユーザーのリクエストがそれより長い場合は、エクスポートを複数回に分けるか、どの週をエクスポートするか確認してください。
• hogql モデルはクローズドベータ版で、チームごとに有効化されます。HogQL のバッチエクスポートが有効になっていないことを示す権限エラーが発生した場合、そのチームではベータ版を利用できません。別のクエリで再試行せず、その旨を報告し、アクセスをリクエストするには PostHog サポートに問い合わせるようユーザーに伝えてください。
• hogql モデルは、ユーザーのクエリの予測が難しいため、他のモデルよりも厳しいリソース制限のもとで実行されます。メモリ、実行時間、読み取りバイト数の制限でエクスポートに失敗した場合は、同じクエリで再試行するのではなく、WHERE 句でクエリを絞り込むよう提案してください。
• hogql モデルは、省略可能な hogql_modifiers オブジェクトを受け付けます。このオブジェクト内の各修飾子は、同じ名前のプロジェクト HogQL 修飾子を今回のエクスポートに限って上書きし、プロジェクトの修飾子は他のすべてのエクスポートに適用されます。プロジェクトで convertToProjectTimezone 修飾子が設定されていない場合、timestamp 列は UTC で出力されます。そのため、プロジェクトのタイムゾーンで表示したい場合は {"convertToProjectTimezone": true} を渡してください。件数をエクスポートと一致させるには、同じ hogql_modifiers を posthog:file-download-batch-exports-count-rows-create に渡してください。
• ファイルレコードの作成中は、完了後もしばらく実行状態が Running と表示されることがあります。すぐに失敗と判断せず、再度ポーリングしてください。
• ダウンロード URL は一時的なものです。URL の有効期限が切れた場合は、REST ダウンロードエンドポイントを再度呼び出して、新しいリダイレクトを取得してください。
• ユーザーから明示的に依頼されない限り、署名付き URL を無関係なサービスに送信しないでください。この URL はエクスポートしたファイルへの一時的なアクセスを許可します。
• 分割したエクスポートのすべてのパートをユーザーが必要としている場合は、files 内のすべての UUID を順に処理してください。パート 0 だけで十分だと決めつけないでください。
• 大規模なバッチエクスポートは、完了まで数分以上かかる場合があります。特定のイベントだけを含めたり、日付範囲を狭めたりすると、ダウンロードを速くできることをユーザーに提案してください。