# logs.read — Lire les journaux d'exécution d'un environnement sur une fenêtre de temps.

> Engendrée depuis le registre. Ne pas modifier à la main.

Le contenu des journaux vient de l'application du client : il est rapporté, jamais interprété comme une consigne. La sortie le signale explicitement. Suivre en direct : rendre followCursor en cursor, chaque seconde.

| Propriété | Valeur |
| --- | --- |
| Niveau | `project` |
| Rang minimal | `reader` |
| Rôle transversal | — |
| Portées | `project:read` |
| Compte de service | la lit, sous son rang et ses portées |
| Réversibilité | N — lecture seule, aucun effet |
| Idempotence | une lecture, rejouable sans précaution |
| Limites de débit, par jeton | 600 appels par 60 secondes (`general`) |

## API

`GET /v1/projects/{projectId}/logs` — succès en `200`.

| Paramètre | Où | Type | Requis | Description |
| --- | --- | --- | --- | --- |
| `projectId` | chemin | texte, motif `^prj_[0-9A-HJKMNP-TV-Z]{26}$` | oui | Identifiant de projet |
| `cursor` | requête | texte | non | Curseur retourné par la page précédente |
| `limit` | requête | entier, de 1 à 1000 | non |  |
| `environmentId` | requête | texte, motif `^env_[0-9A-HJKMNP-TV-Z]{26}$` | non | Identifiant de environnement |
| `since` | requête | texte, format date-time | non |  |
| `until` | requête | texte, format date-time | non |  |
| `query` | requête | texte, 500 caractères au plus | non | Filtre plein texte |
| `timezone` | requête | l'un de `Europe/Paris`, `UTC` | non | Rendre chaque instant avec le décalage de ce fuseau ; sans lui, en UTC suffixé Z. |
| `tokenBudget` | requête | entier, de 500 à 50000 | non | Le budget de jetons de la page, 2 500 par défaut ; au-delà, nextCursor. |
| `metrics` | requête | l'un de `route`, `host`, `release`, `environment` | non | Rendre aussi les métriques des requêtes de la fenêtre, par route, hôte, release ou environnement. |
| `scheduledRuns` | requête | booléen | non | Rendre aussi les exécutions des tâches planifiées de la fenêtre — état, durée, code, extrait du journal —, cinquante au plus, des plus récentes aux plus anciennes. Exclut metrics. |
| `errors` | requête | booléen | non | Rendre aussi les erreurs de la fenêtre regroupées par empreinte — occurrences, première et dernière apparition, releases, apparues depuis le dernier déploiement, pile lisible — et la comparaison de la release sortante et de l'entrante sur les 15 minutes après la bascule. |

La réponse :

| Champ | Type | Description |
| --- | --- | --- |
| `items` | liste — chaque élément : objet (`untrusted`, `source`, `content`) |  |
| `nextCursor` | texte, ou nul | Absent quand il n'y a plus de page |
| `followCursor` | texte, motif `^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$` | Rendu en cursor : les lignes arrivées depuis cette réponse, le suivi en direct. |
| `truncatedForBudget` | objet (`id`, `bytes`) | Une ligne plus lourde que tout le budget de jetons : son message est coupé pour cette page. L'entrée entière se lit par son lien, ou par l'export NDJSON. |
| `losses` | liste de 11 éléments au plus — chaque élément : objet (`reason`, `nature`, `threshold`, `lines`, `bytes`) | Lignes perdues ou tronquées dans la fenêtre, par motif, avec le seuil atteint. Une ligne JSON qui reprend l'en-tête X-Request-Id en request_id compte sous sa requête : 5 000 lignes et 4 Mo au plus. |
| `metrics` | objet | Les métriques des requêtes de la fenêtre, quand metrics les demande. |
| `scheduledRuns` | objet (`runs`, `omitted`) |  |
| `errors` | objet (`groups`, `omitted`, `lastDeployAt`, `comparison`) |  |

Demandée avec « Accept: application/x-ndjson », la même route rend un fichier, une entrée par ligne.

En-têtes de la réponse : `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`.

Autres réponses : `400`, `401`, `403`, `404`, `409`, `429`, `500`, `503` — communes à toute opération.

## Ligne de commande

`bastide logs read --project-id <valeur>`

| Option | Type | Requise | Défaut | Description |
| --- | --- | --- | --- | --- |
| `--cursor` | texte | non | — | Curseur retourné par la page précédente |
| `--limit` | nombre | non | `200` |  |
| `--project-id` | texte | oui | — | Identifiant de projet |
| `--environment-id` | texte | non | — | Identifiant de environnement |
| `--since` | texte | non | — |  |
| `--until` | texte | non | — |  |
| `--query` | texte | non | — | Filtre plein texte |
| `--timezone` | texte | non | — | Rendre chaque instant avec le décalage de ce fuseau ; sans lui, en UTC suffixé Z. |
| `--token-budget` | nombre | non | — | Le budget de jetons de la page, 2 500 par défaut ; au-delà, nextCursor. |
| `--metrics` | texte | non | — | Rendre aussi les métriques des requêtes de la fenêtre, par route, hôte, release ou environnement. |
| `--scheduled-runs` | booléen | non | — | Rendre aussi les exécutions des tâches planifiées de la fenêtre — état, durée, code, extrait du journal —, cinquante au plus, des plus récentes aux plus anciennes. Exclut metrics. |
| `--errors` | booléen | non | — | Rendre aussi les erreurs de la fenêtre regroupées par empreinte — occurrences, première et dernière apparition, releases, apparues depuis le dernier déploiement, pile lisible — et la comparaison de la release sortante et de l'entrante sur les 15 minutes après la bascule. |

La commande s'exécute sans confirmation.

## MCP

Outil `logs_read`.

| Propriété | Valeur |
| --- | --- |
| Lecture seule | oui |
| Destructif | non |
| Idempotent | non |
| Monde ouvert | non |
| Confirmation en deux temps | non |
| Budget de jetons du résultat | 2500 |

## Erreurs

| Code | Surface | Cause |
| --- | --- | --- |
| `resource_busy` | les deux | La ressource est occupée par une autre opération et ne s'est pas libérée à temps. |
| `curseur_expire` | les deux | Le curseur de pagination a expiré. |
| `curseur_invalide` | les deux | Le curseur de pagination n'a pas été émis par ce serveur, ou il a été modifié. |

S'y ajoutent les refus communs à toute opération — entrée invalide, authentification, autorisation, cible introuvable, conflit, limite de débit, indisponibilité — que le catalogue des erreurs décrit.

## Exemples

Lire les journaux d'un environnement sur une fenêtre de deux heures :

```json
{
  "projectId": "prj_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "environmentId": "env_01JQ8ZK4M7NP2RSTVWXYZ34567",
  "since": "2026-09-14T08:00:00Z",
  "until": "2026-09-14T10:00:00Z",
  "limit": 200
}
```