Downloading Batch Export Files

1---
2name: downloading-batch-export-files
3description: >
4  Export PostHog events, persons, or sessions on demand and download the resulting files. Use when the user asks to
5  download/export raw PostHog data, create a one-off file export, fetch a Parquet or JSONLines export, or use the
6  file_download_batch_exports API. Covers starting the export with MCP, polling completion, and downloading via the
7  existing REST redirect endpoint.
8---
9 
10# Downloading batch export files
11 
12Use this skill when a user wants a one-off downloadable export of PostHog data.
13The export is started and monitored through MCP, but the final file download uses the existing REST endpoint directly.
14 
15## Available MCP tools
16 
17| Tool                                           | Purpose                                                  |
18| ---------------------------------------------- | -------------------------------------------------------- |
19| `posthog:file-download-batch-exports-create`   | Start an on-demand export and return the run ID          |
20| `posthog:file-download-batch-exports-retrieve` | Poll the run status and return file IDs after completion |
21 
22Do not rely on a generated MCP tool for the `/download/` endpoint.
23That endpoint is a redirecting file download endpoint, so raw HTTP/download handling is the right interface until MCP has explicit redirect support.
24 
25## Workflow
26 
27### 1. Choose the export shape
28 
29Ask a short clarifying question if the user did not specify the required inputs:
30 
31- `model`: one of `events`, `persons`, or `sessions`
32- `data_interval_start` and `data_interval_end`: ISO 8601 datetimes; the range must be at most one week
33- `file.format`: `Parquet` or `JSONLines`; prefer `Parquet` for compact analytics exports and `JSONLines` for line-oriented text processing
34- `file.compression`: optional, one of `zstd`, `gzip`, `brotli`, `lz4`, or `snappy`. If `JSONLines` was chosen as format, only `gzip` and `brotli` are supported.
35- `file.max_size_mb`: optional maximum part size in MB; set this when the user wants multiple smaller files instead of a single (potentially large) file.
36 
37For `events`, `include` and `exclude` are optional event-name filters.
38Use them only when the user asks for specific events or wants to omit specific events.
39 
40### 2. Start the export
41 
42Call `posthog:file-download-batch-exports-create` with the selected shape.
43The response contains an `id` for the export run.
44 
45Example request:
46 
47```json
48{
49  "model": "events",
50  "file": {
51    "format": "JSONLines",
52    "compression": "gzip"
53  },
54  "include": ["$pageview"],
55  "data_interval_start": "2026-05-25T00:00:00Z",
56  "data_interval_end": "2026-05-26T00:00:00Z"
57}
58```
59 
60### 3. Poll until completion
61 
62Call `posthog:file-download-batch-exports-retrieve` with the returned `id`.
63 
64Status handling:
65 
66| Status                                                                    | Action                                        |
67| ------------------------------------------------------------------------- | --------------------------------------------- |
68| `Starting` or `Running`                                                   | Wait briefly and poll again                   |
69| `Completed`                                                               | Read the `files` array and download each file |
70| `Cancelled`                                                               | Stop and report that the run was cancelled    |
71| `Failed`, `FailedRetryable`, `FailedBilling`, `Terminated`, or `TimedOut` | Stop and report the `error` field             |
72 
73When `Completed`, the `files` array contains file UUIDs.
74For single-file exports it usually contains one UUID.
75For split exports, download every UUID unless the user asked for a specific part.
76 
77### 4. Optionally, cancel a running export
78 
79If required by the user, a running export can be cancelled by calling `posthog:file-download-batch-exports-cancel-create` with the returned `id`.
80 
81An export that has already finished or has already failed may not be cancelled.
82 
83After cancelling an export, the `id` may not be used anymore and the export must start again from the beginning. However, you may still use the `id` to retrieve the export status (which will always be `Cancelled`).
84 
85### 5. Download files through REST
86 
87Use a direct authenticated HTTP request to the existing endpoint:
88 
89```text
90GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/{part}/
91```
92 
93`part` can be either:
94 
95- a file UUID from the `files` array returned by `file-download-batch-exports-retrieve`
96- a zero-based file index, ordered by key
97 
98If there is only one file, this also works without `part`:
99 
100```text
101GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/
102```
103 
104Let the HTTP client follow the redirect, or inspect the `Location` header if you need the temporary signed URL.
105Use the same PostHog authentication context as other API calls.
106 
107### 6. Save, do not print, file contents
108 
109Treat the result as a file download, not a chat response.
110Parquet is binary and must be written as bytes.
111JSONLines may still be large; save it to a file rather than pasting the contents unless the user explicitly asks for a tiny sample.
112 
113Use a filename that includes the model, run ID, and part identifier when possible, for example:
114 
115```text
116posthog-events-<run_id>-<part>.jsonl.gz
117posthog-persons-<run_id>-<part>.parquet
118```
119 
120## Watch-outs
121 
122- The maximum export interval is one week. Split longer user requests into separate export runs or ask which week to export.
123- A run can briefly report `Running` after completion while file records are being created. Poll again instead of failing immediately.
124- Download URLs are temporary. If a URL expires, call the REST download endpoint again for a fresh redirect.
125- Do not send the signed URL to unrelated services unless the user explicitly asks; it grants temporary access to the exported file.
126- If the user wants all parts of a split export, iterate over every UUID in `files`; do not assume part `0` is enough.
127- Large batch exports may take a few minutes or even longer to complete. Suggest to the user that they can speed-up their download by including only certain events or narrowing the date range.
128