/downloading-batch-export-files

name: downloading-batch-export-files
description: >
  Export PostHog events, persons, sessions, or the results of a HogQL query on demand and download the resulting
  files. Use when the user asks to download/export raw PostHog data, export HogQL query results, create a one-off
  file export, fetch a Parquet or JSONLines export, or use the file_download_batch_exports API.
  Covers starting the export with MCP, polling completion, and downloading via the existing REST redirect endpoint.

Downloading batch export files

Use this skill when a user wants a one-off downloadable export of PostHog data. The export is started and monitored through MCP, but the final file download uses the existing REST endpoint directly.

Available MCP tools

| Tool | Purpose | | ---------------------------------------------- | -------------------------------------------------------- | | `posthog:file-download-batch-exports-create` | Start an on-demand export and return the run ID | | `posthog:file-download-batch-exports-retrieve` | Poll the run status and return file IDs after completion |

Do not rely on a generated MCP tool for the `/download/` endpoint. That endpoint is a redirecting file download endpoint, so raw HTTP/download handling is the right interface until MCP has explicit redirect support.

Workflow

1. Choose the export shape

Ask a short clarifying question if the user did not specify the required inputs:

• `model`: one of `events`, `persons`, `sessions`, or `hogql`
• `data_interval_start` and `data_interval_end`: ISO 8601 datetimes. Any supplied bound may not be in the future. When both bounds are supplied, they must be ordered and at most one week apart

Required for `events`, `persons`, and `sessions`. For `hogql`, required only for the placeholders the query references. If only one placeholder is referenced, the other bound may be omitted and the one-week limit does not apply.

• `file.format`: `Parquet` or `JSONLines`; prefer `Parquet` for compact analytics exports and `JSONLines` for line-oriented text processing
• `file.compression`: optional, one of `zstd`, `gzip`, `brotli`, `lz4`, or `snappy`. If `JSONLines` was chosen as format, only `gzip` and `brotli` are supported.
• `file.max_size_mb`: part size in MiB, 1024 by default. A part can go a little over this size.

Lower it when the user wants smaller parts, raise it for fewer and bigger ones, or set it to `null` to write a single file of any size.

For `events`, `include` and `exclude` are optional event-name filters. Use them only when the user asks for specific events or wants to omit specific events.

For `hogql`, pass the query as `hogql_query` and leave out `include` and `exclude`. You may prompt the user to export a slice of data by including a WHERE clause in the HogQL query, for example limiting results from the `events` table by bounding `timestamp`. Always prefer limiting the data exported to the minimum necessary to solve the user's request. Every column in the SELECT clause must be a field or have an alias. This model is in closed beta and is enabled per team.

A `hogql` query can reference the `{data_interval_start}` and `{data_interval_end}` placeholders. The export replaces them with the `data_interval_start` and `data_interval_end` values, so one query can export any interval. Supply a bound for every placeholder the query references; a missing bound fails the request. The bounds only replace placeholders and do not filter anything themselves, so a query without placeholders runs unchanged even when bounds are supplied. Prefer placeholders over literal dates when the user wants a time range, or several consecutive ranges from the same query. Compare with `>= {data_interval_start}` and `< {data_interval_end}`, so consecutive ranges do not export the same row twice.

2. Start the export

Call `posthog:file-download-batch-exports-create` with the selected shape. The response contains an `id` for the export run.

Example request:

{
  "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"
}

Example request for the `hogql` model:

{
  "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. Poll until completion

Call `posthog:file-download-batch-exports-retrieve` with the returned `id`.

Status handling:

| Status | Action | | ------------------------------------------------------------------------- | --------------------------------------------- | | `Starting` or `Running` | Wait briefly and poll again | | `Completed` | Read the `files` array and download each file | | `Cancelled` | Stop and report that the run was cancelled | | `Failed`, `FailedRetryable`, `FailedBilling`, `Terminated`, or `TimedOut` | Stop and report the `error` field |

When `Completed`, the `files` array contains file UUIDs. For single-file exports it usually contains one UUID. For split exports, download every UUID unless the user asked for a specific part.

A `Completed` response also carries `records_completed`, the number of rows the run exported. Report it to the user, because the count is otherwise only visible by opening every file.

4. Optionally, cancel a runnin