Datasets, stockage & fichiers

Chaque exécution laisse quelque chose derrière elle : des lignes dans un dataset, une table interrogeable par workflow, et des fichiers. Cette page est la carte de l’endroit où atterrit cette sortie, de la façon de l’interroger et de la fouiller, de sa durée de conservation, et des plafonds que le stockage de fichiers applique.

Tout ici est cloisonné à votre organisation : un id qui n’est pas le vôtre répond 404, jamais un 403 qui confirmerait son existence.

datasets ▸ un par source

Datasets

Un dataset est la sortie accumulée d’une source — un crawl ou un workflow. La liste vous dit d’où vient chacun et sa fraîcheur : chaque entrée porte un source_type (crawl ou workflow), son run_count et son horodatage last_updated.

Endpoint	Rôle
`GET /api/v1/datasets`	Liste vos datasets avec `source_type`, `run_count`, `last_updated`.
`GET /api/v1/datasets/{id}/records`	Parcourt les enregistrements d’un dataset, page par page.
`GET /api/v1/datasets/search`	Une requête sur tous vos datasets à la fois (sémantique ci-dessous).
`DELETE /api/v1/datasets/{id}` · `…/records`	Supprime un dataset, ou seulement ses enregistrements. Exige le scope `datasets:delete`.

tables ▸ des lignes par run

Tables de workflow

Chaque workflow expose aussi sa sortie sous forme d’une table. Une exécution qui a extrait une liste contribue une ligne par enregistrement — une exécution qui a relevé 40 produits ajoute 40 lignes, pas un seul bloc. Chaque ligne porte sa provenance : run_id, run_at et status, et les entrées avec lesquelles l’exécution a été appelée apparaissent comme colonnes input.<name>, valeurs secrètes caviardées.

Endpoint	Rôle
`GET /api/v1/workflows/{id}/data`	La table elle-même : filtrer, trier, paginer.
`GET /api/v1/workflows/{id}/data/facets`	Valeurs distinctes par colonne, pour construire des filtres.
`GET /api/v1/workflows/{id}/data/export`	La même table en téléchargement (formats ci-dessous).

Param	Signification
`q`	Correspondance par sous-chaîne sur tous les champs de données et les entrées.
`filter`	Paires `column:substring`, répétables.
`filters`	Clauses JSON, pour les conditions que `filter` ne sait pas exprimer.
`sort_by` / `sort_dir`	Une colonne de données, une colonne `input.<name>`, ou `run_at` \| `status` \| `duration_ms`.
`limit` / `offset`	`limit` de 1 à 500, 50 par défaut.
`include_inputs`	Ajoute les colonnes `input.<name>` à la réponse.
`collection`	Pivote un tableau imbriqué en une ligne par élément.

recherche ▸ sur tout

Recherche

GET /api/v1/datasets/search exécute une requête sur tous les datasets que vous détenez. Le même appel s’écrit datasets.search dans chaque SDK :

const hits = await client.datasets.search("invoice 2291", { limit: 20 });

hits = client.datasets.search("invoice 2291", limit=20)

hits, err := client.Datasets.Search(ctx, "invoice 2291", nil)

let hits = agent.datasets().search("invoice 2291").await?;

curl "http://127.0.0.1:8131/v1/datasets/search?q=invoice+2291" \
  -H "Authorization: Bearer $WRIT_TOKEN"

La sémantique est volontairement petite, et mérite d’être connue exactement :

Les termes séparés par des espaces sont combinés en ET ; chaque terme correspond par préfixe, sans tenir compte de la casse.
Les opérateurs de phrase et booléens ne sont volontairement pas pris en charge ; une requête accepte au plus 8 termes.
Les candidats sont plafonnés aux 500 correspondances les plus récentes — la réponse pose un indicateur truncated quand le plafond est atteint.
Les extraits montrent 80 caractères de contexte autour de la correspondance ; limit va de 1 à 200, 50 par défaut.

export ▸ quatre formats

Formats d’export

Tables et datasets se rendent en quatre formats :

Format	Défaut pour
`json`	Les réponses API.
`csv`	Les téléchargements.
`markdown`	—
`html`	—

rétention ▸ combien de temps

Rétention

Enregistrement	Conservé
Exécutions	90 jours
Journaux	90 jours
Changements détectés	90 jours
Événements d’audit	400 jours (~13 mois)

Ce sont les fenêtres par défaut.

fichiers ▸ le côté octets

Fichiers

Les fichiers vivent dans un stockage objet par tenant, adressés par une poignée stable file_…, et sont servis par la Files API sur /api/v1/files (envoi, liste, lecture, téléchargement, suppression). Un téléchargement est un 302 vers un lien signé, mono-objet, qui expire en 600 s — l’hôte de stockage et ses identifiants ne sont donc jamais exposés.

Plafond par fichier : 100 Mo — il s’applique à chaque fichier, quelle que soit son origine.
Les fichiers produits par workflow_output, ai_session ou streaming sont éphémères : TTL de 24 h, sauf si vous les promouvez dans la bibliothèque.
Les types de contenu exécutables sont refusés par défaut.
Le contrôle de propriété répond 404 pour tout ce qui n’est pas à vous — jamais un 403 qui trahirait une existence.

quota ▸ par palier

Quota de stockage

Chaque palier porte un quota de stockage de fichiers pour l’organisation :

Palier	Stockage
Free	1 Go
Starter	2 Go
Pro	5 Go
Growth	50 Go
Scale	200 Go
Enterprise	1000 Go

Un quota plein répond un 402 de stockage — une erreur distincte du 402 de crédits. Libérer de l’espace (ou un palier supérieur) règle le premier ; des fonds règlent le second.

byo ▸ votre propre bucket

Apportez votre propre stockage

Par défaut, les octets résident dans le stockage géré de Writ. Vous pouvez à la place pointer Writ vers un bucket compatible S3 que vous contrôlez — s3, minio, r2 ou spaces — dans Settings → Storage. La clé secrète est en écriture seule (chiffrée au repos, jamais renvoyée), un test de connexion côté serveur sonde le bucket avant sa mise en service, et changer de fournisseur par défaut ne casse jamais le téléchargement des fichiers déjà stockés.

Et ensuite

Workflows : d’où viennent les lignes.
Référence API : formes des requêtes et réponses, codes de statut.
Automatisations & webhooks : poussez la sortie plus loin au lieu de la relever.
Facturation & usage : ce que signifie un 402 de crédits, et les trois sorties.