Télécharger les fichiers d'export par batch

Utilisez cette compétence quand un utilisateur souhaite un export téléchargeable ponctuel de données PostHog. L'export est lancé et suivi via MCP, mais le téléchargement du fichier final utilise directement l'endpoint REST existant.

Outils MCP disponibles

Ne vous fiez pas à un outil MCP généré pour l'endpoint /download/. Cet endpoint est un endpoint de téléchargement fichier avec redirection, donc la gestion HTTP/téléchargement brute est la bonne interface tant que MCP n'a pas de support explicite des redirections.

Flux de travail

1. Choisir la forme d'export

Posez une brève question de clarification si l'utilisateur n'a pas spécifié les entrées requises :

• model : l'un de events, persons, ou sessions
• data_interval_start et data_interval_end : datetimes ISO 8601 ; la plage doit faire au maximum une semaine
• file.format : Parquet ou JSONLines ; privilégiez Parquet pour les exports analytics compacts et JSONLines pour le traitement de texte orienté lignes
• file.compression : optionnel, l'un de zstd, gzip, brotli, lz4, ou snappy. Si JSONLines a été choisi comme format, seuls gzip et brotli sont supportés.
• file.max_size_mb : taille maximale optionnelle des parties en MB ; définissez-la quand l'utilisateur préfère plusieurs fichiers plus petits au lieu d'un seul fichier (potentiellement gros).

Pour events, include et exclude sont des filtres optionnels sur les noms d'événements. Ne les utilisez que quand l'utilisateur demande des événements spécifiques ou veut en exclure.

2. Lancer l'export

Appelez posthog:file-download-batch-exports-create avec la forme sélectionnée. La réponse contient un id pour la run d'export.

Exemple de requête :

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

3. Interroger jusqu'à la fin

Appelez posthog:file-download-batch-exports-retrieve avec l'id retourné.

Gestion du statut :

Quand Completed, le tableau files contient les UUIDs des fichiers. Pour les exports monofichier il contient généralement un UUID. Pour les exports partitionnés, téléchargez tous les UUIDs sauf si l'utilisateur a demandé une partie spécifique.

4. Optionnellement, annuler un export en cours

Si demandé par l'utilisateur, un export en cours peut être annulé en appelant posthog:file-download-batch-exports-cancel-create avec l'id retourné.

Un export déjà terminé ou déjà échoué ne peut pas être annulé.

Après annulation d'un export, l'id ne peut plus être utilisé et l'export doit recommencer du début. Vous pouvez toutefois encore utiliser l'id pour récupérer le statut d'export (qui sera toujours Cancelled).

5. Télécharger les fichiers via REST

Utilisez une requête HTTP authentifiée directe vers l'endpoint existant :

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

part peut être soit :

• un UUID de fichier du tableau files retourné par file-download-batch-exports-retrieve
• un index de fichier en base zéro, ordonné par clé

S'il n'y a qu'un seul fichier, cela fonctionne aussi sans part :

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

Laissez le client HTTP suivre la redirection, ou inspectez le header Location si vous avez besoin de l'URL temporaire signée. Utilisez le même contexte d'authentification PostHog que les autres appels API.

6. Enregistrer, ne pas afficher, le contenu des fichiers

Traitez le résultat comme un téléchargement de fichier, pas comme une réponse de chat. Parquet est binaire et doit être écrit en bytes. JSONLines peut être volumineux ; enregistrez-le dans un fichier plutôt que de coller le contenu, sauf si l'utilisateur demande explicitement un petit échantillon.

Utilisez un nom de fichier qui inclut le modèle, l'ID de la run et l'identifiant de partie si possible, par exemple :

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

Points d'attention

• L'intervalle d'export maximum est une semaine. Divisez les demandes utilisateur plus longues en runs d'export séparées ou demandez quelle semaine exporter.
• Une run peut brièvement signaler Running après la fin pendant que les enregistrements de fichier sont créés. Interrogez à nouveau au lieu de échouer immédiatement.
• Les URLs de téléchargement sont temporaires. Si une URL expire, appelez à nouveau l'endpoint de téléchargement REST pour une nouvelle redirection.
• N'envoyez pas l'URL signée à des services non liés sauf si l'utilisateur le demande explicitement ; elle accorde un accès temporaire au fichier exporté.
• Si l'utilisateur veut toutes les parties d'un export partitionné, itérez sur tous les UUIDs dans files ; ne supposez pas que la partie 0 suffit.
• Les exports batch volumineux peuvent prendre quelques minutes ou plus pour se terminer. Suggérez à l'utilisateur qu'il peut accélérer son téléchargement en incluant seulement certains événements ou en réduisant la plage de dates.