|
| 1 | +--- |
| 2 | +name: downloading-batch-export-files |
| 3 | +description: > |
| 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 | + |
| 12 | +Use this skill when a user wants a one-off downloadable export of PostHog data. |
| 13 | +The 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 | + |
| 22 | +Do not rely on a generated MCP tool for the `/download/` endpoint. |
| 23 | +That 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 | + |
| 29 | +Ask 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 | + |
| 37 | +For `events`, `include` and `exclude` are optional event-name filters. |
| 38 | +Use them only when the user asks for specific events or wants to omit specific events. |
| 39 | + |
| 40 | +### 2. Start the export |
| 41 | + |
| 42 | +Call `posthog:file-download-batch-exports-create` with the selected shape. |
| 43 | +The response contains an `id` for the export run. |
| 44 | + |
| 45 | +Example 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 | + |
| 62 | +Call `posthog:file-download-batch-exports-retrieve` with the returned `id`. |
| 63 | + |
| 64 | +Status 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 | + |
| 73 | +When `Completed`, the `files` array contains file UUIDs. |
| 74 | +For single-file exports it usually contains one UUID. |
| 75 | +For split exports, download every UUID unless the user asked for a specific part. |
| 76 | + |
| 77 | +### 4. Optionally, cancel a running export |
| 78 | + |
| 79 | +If required by the user, a running export can be cancelled by calling `posthog:file-download-batch-exports-cancel-create` with the returned `id`. |
| 80 | + |
| 81 | +An export that has already finished or has already failed may not be cancelled. |
| 82 | + |
| 83 | +After 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 | + |
| 87 | +Use a direct authenticated HTTP request to the existing endpoint: |
| 88 | + |
| 89 | +```text |
| 90 | +GET /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 | + |
| 98 | +If there is only one file, this also works without `part`: |
| 99 | + |
| 100 | +```text |
| 101 | +GET /api/projects/{project_id}/file_download_batch_exports/{run_id}/download/ |
| 102 | +``` |
| 103 | + |
| 104 | +Let the HTTP client follow the redirect, or inspect the `Location` header if you need the temporary signed URL. |
| 105 | +Use the same PostHog authentication context as other API calls. |
| 106 | + |
| 107 | +### 6. Save, do not print, file contents |
| 108 | + |
| 109 | +Treat the result as a file download, not a chat response. |
| 110 | +Parquet is binary and must be written as bytes. |
| 111 | +JSONLines may still be large; save it to a file rather than pasting the contents unless the user explicitly asks for a tiny sample. |
| 112 | + |
| 113 | +Use a filename that includes the model, run ID, and part identifier when possible, for example: |
| 114 | + |
| 115 | +```text |
| 116 | +posthog-events-<run_id>-<part>.jsonl.gz |
| 117 | +posthog-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. |
0 commit comments