downloading-batch-export-files

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; the range must be at most one week. Required for events, persons, and sessions, and not supported for hogql
• 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: optional maximum part size in MB; set this when the user wants multiple smaller files instead of a single (potentially large) file.

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 data_interval_start, data_interval_end, include, and exclude. The query runs as of the time the export starts, so there is no interval to choose. 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, and placeholders are not supported. This model is in closed beta and is enabled per team.

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 > now() - INTERVAL 1 HOUR"
}

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

Status handling:

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.

If required by the user, a running export can be cancelled by calling posthog:file-download-batch-exports-cancel-create with the returned id.

An export that has already finished or has already failed may not be cancelled.

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).

Use a direct authenticated HTTP request to the existing endpoint:

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

part can be either:

• a file UUID from the files array returned by file-download-batch-exports-retrieve
• a zero-based file index, ordered by key

If there is only one file, this also works without part:

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

Let the HTTP client follow the redirect, or inspect the Location header if you need the temporary signed URL. Use the same PostHog authentication context as other API calls.

Treat the result as a file download, not a chat response. Parquet is binary and must be written as bytes. JSONLines may still be large; save it to a file rather than pasting the contents unless the user explicitly asks for a tiny sample.

Use a filename that includes the model, run ID, and part identifier when possible, for example:

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