# Utilisation et journal d’audit par l’API

> Lire l’utilisation par membre, par groupe et par modèle, l’exporter en CSV, puis lire, filtrer et exporter le journal d’audit de l’organisation par l’API.

Toutes les routes sont sous `https://chat.realmoon.ai/api/v1/orgs/{org_id}`. Portées : `usage:read` pour l’utilisation, `audit:read` pour le journal. Il n’existe pas de portée d’écriture pour ces domaines.

## Utilisation

### Ce qui est compté

| Mesure | Description |
| --- | --- |
| `requests` | Demandes : une par réponse de conversation, image, vidéo ou service (recherche web, ordinateur, voix, musique). Les tâches de fond (titres, suggestions) ne comptent pas. |
| `tokens_in`, `tokens_out`, `tokens` | Jetons des réponses des modèles : entrée, sortie, total. Les images, vidéos et services n’en ont pas. |
| `share`, `token_share`, `request_share` | Part, en pourcentage, de l’utilisation de l’organisation (ou des groupes choisis). |
| `month_pct` | Part de sa limite du mois que le membre a déjà utilisée, maintenant, quelle que soit la période demandée. |

`usage_scope` vaut `workspace` quand l’organisation compte l’utilisation de ses membres, `personal` quand chaque membre utilise sa propre allocation : les chiffres sont alors vides.

### Période et périmètre

| Paramètre | Description |
| --- | --- |
| `date_from`, `date_to` | Secondes Unix ; `date_to` est exclu. Par défaut, les 30 derniers jours. 366 jours au plus. |
| `group_id` | Ne compter que les membres de ce groupe (sauf pour `/usage/groups`). |

Une période invalide répond `400 invalid_request` (« Période invalide : 366 jours au plus. »). Les réponses rendent `date_from` et `date_to` effectifs, et `scope` : `org` (toute l’organisation), `managed_groups` (les groupes que le créateur de la clé gère, sans adresses e-mail) ou `self` (le créateur seul).

### Totaux de la période

`GET /usage/summary` · `usage:read`

```bash title="cURL"
curl "https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/usage/summary?date_from=1759622400&date_to=1762214400" \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY"
```

```python title="Python"
import os
import time
import requests

now = int(time.time())
r = requests.get(
    f"https://chat.realmoon.ai/api/v1/orgs/{os.environ['ORG_ID']}/usage/summary",
    headers={"Authorization": f"Bearer {os.environ['MOONAI_ADMIN_KEY']}"},
    params={"date_from": now - 30 * 86400, "date_to": now},
    timeout=30,
)
r.raise_for_status()
summary = r.json()
print(summary["current"]["requests"], summary["near_limit"])
```

```javascript title="JavaScript"
const now = Math.floor(Date.now() / 1000);
const url = new URL(`https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}/usage/summary`);
url.search = new URLSearchParams({ date_from: now - 30 * 86400, date_to: now });
const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}` } });
if (!r.ok) throw new Error(await r.text());
const summary = await r.json();
console.log(summary.current.requests, summary.near_limit);
```

```json
{
  "date_from": 1759622400,
  "date_to": 1762214400,
  "current": { "members": 380, "active_members": 295, "requests": 18422, "tokens_in": 91200000, "tokens_out": 6100000, "tokens": 97300000 },
  "previous": { "members": 379, "active_members": 280, "requests": 17003, "tokens_in": 85000000, "tokens_out": 5700000, "tokens": 90700000 },
  "month_pct_avg": 37.4,
  "near_limit": 4,
  "days": [{ "day": "2026-10-05", "requests": 512, "active": 81, "tokens_in": 2500000, "tokens_out": 170000 }],
  "usage_scope": "workspace",
  "scope": "org",
  "can_export": true
}
```

`previous` couvre la période précédente de même durée. `near_limit` compte les membres à 90 % ou plus de leur limite du mois. `days` (jours de l’heure de Paris) n’est rendu que pour une période de 92 jours au plus.

### Par membre

`GET /usage` · `usage:read`

| Paramètre | Description |
| --- | --- |
| `q` | Partie du nom ou de l’adresse. |
| `sort` | `requests` (par défaut), `usage`, `month_pct`, `name`, `last_request` ou `tokens`. |
| `page`, `limit` | 50 par défaut, 200 au plus. |

Chaque élément : `user_id`, `name`, `email`, `profile_image_url`, `role`, `last_active_at`, `last_request_at`, `requests`, `share`, `month_pct`, `tokens_in`, `tokens_out`, `tokens`, `token_share`. La réponse ajoute `totals` pour tout le périmètre.

### Par groupe

`GET /usage/groups` · `usage:read`

Paramètres : `q`, `sort` (`requests`, `usage`, `tokens`, `active`, `members`, `name`), `page`, `limit`. Chaque élément : `id`, `name`, `kind` (`static` ou `dynamic`), `members`, `active_members`, `requests`, `share`, `tokens_in`, `tokens_out`, `tokens`, `token_share`. Un membre de plusieurs groupes compte dans chacun : la somme des parts peut dépasser 100.

### Par modèle

`GET /usage/models` · `usage:read`

Jusqu’à 100 modèles, avec `model_id` (le modèle qui a répondu), `name`, `kind`, `requests`, `share`, `request_share` et les jetons. `model_id` vaut `image` ou `video` (`kind: "media"`) pour les créations d’images et de vidéos ; les services ne figurent pas ici.

### Exporter en CSV

`GET /usage/export?view=members` · `usage:read`

`view` vaut `members` (par défaut), `groups` ou `models` ; `date_from`, `date_to` et `group_id` s’appliquent. Le fichier est en UTF-8 avec BOM, séparé par des virgules ; une cellule qui commence par `=`, `+`, `-` ou `@` est précédée d’une apostrophe. Les adresses e-mail n’y figurent qu’avec un périmètre `org`. L’export est inscrit au journal.

## Journal d’audit

Chaque action d’administration est inscrite au journal de l’organisation, avec son auteur : un membre, une clé d’administration (`api_key:<id>`) ou Moon AI.

### Filtres

| Paramètre | Description |
| --- | --- |
| `action` | Un ou plusieurs codes d’action séparés par des virgules (50 au plus). |
| `actor_id` | Un membre, `api_key:<id>`, ou `__platform__` pour Moon AI. |
| `target_id` | La personne visée, ou tout identifiant présent dans le détail (groupe, étiquette, rôle). |
| `q` | Texte cherché dans le détail et dans le nom ou l’adresse de la personne visée. |
| `date_from`, `date_to` | Secondes Unix ; `date_to` exclu. |
| `include_switches` | `true` pour voir aussi les changements de workspace (cachés par défaut). |

### Lire le journal

`GET /audit` · `audit:read`

```bash title="cURL"
curl "https://chat.realmoon.ai/api/v1/orgs/$ORG_ID/audit?action=org_member_remove&limit=20" \
  -H "Authorization: Bearer $MOONAI_ADMIN_KEY"
```

```python title="Python"
import os
import requests

r = requests.get(
    f"https://chat.realmoon.ai/api/v1/orgs/{os.environ['ORG_ID']}/audit",
    headers={"Authorization": f"Bearer {os.environ['MOONAI_ADMIN_KEY']}"},
    params={"action": "org_member_remove", "limit": 20},
    timeout=30,
)
r.raise_for_status()
for line in r.json()["items"]:
    print(line["created_at"], line["actor"]["name"], line["action"])
```

```javascript title="JavaScript"
const url = new URL(`https://chat.realmoon.ai/api/v1/orgs/${process.env.ORG_ID}/audit`);
url.search = new URLSearchParams({ action: 'org_member_remove', limit: 20 });
const r = await fetch(url, { headers: { Authorization: `Bearer ${process.env.MOONAI_ADMIN_KEY}` } });
if (!r.ok) throw new Error(await r.text());
for (const line of (await r.json()).items) console.log(line.created_at, line.actor.name, line.action);
```

```json
{
  "items": [
    {
      "id": 918273,
      "action": "org_group_members_add",
      "created_at": 1762209000,
      "actor": { "id": "api_key:7c1e2a4b-6d8f-4a0c-9e2b-4d6f8a0c2e4b", "name": "Synchro annuaire", "email": null, "kind": "api_key" },
      "target": null,
      "object": { "type": "group", "id": "<id de groupe>", "name": "Professeurs" },
      "count": 3,
      "changes": null,
      "before": null,
      "after": { "group_id": "<id de groupe>", "user_ids": ["<id 1>", "<id 2>", "<id 3>"] },
      "ip": "203.0.113.10",
      "user_agent": "curl/8.5.0",
      "people": [{ "id": "<id 1>", "name": "Léa Dupont" }]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50,
  "can_export": true
}
```

| Champ | Description |
| --- | --- |
| `actor.kind` | `member`, `api_key`, `platform` (Moon AI) ou `system` (tâche automatique). |
| `target` | La personne visée ; `deleted: true` si son compte n’existe plus. |
| `object` | L’objet touché : groupe, étiquette, rôle, membre, règles, domaine, serveur MCP, modèle ou ressource. |
| `changes` | Liste `{path, before, after}` (40 au plus) pour les règles, réglages, rôles et statuts. |
| `before`, `after` | Le détail brut de l’action. |
| `people` | Les 5 premières personnes touchées, quand l’action en vise plusieurs. |

Pour les actions qu’un membre fait sur son propre compte, l’adresse IP, le navigateur et le détail ne sont pas rendus. Les lignes de Moon AI n’ont pas d’adresse IP.

### Actions et auteurs présents

`GET /audit/facets` · `audit:read`

Rend `actions` (chaque code présent et son nombre de lignes) et `actors` (200 auteurs au plus, les plus actifs d’abord), pour construire des filtres.

### Exporter le journal

`GET /audit/export` · `audit:read`

CSV des lignes qui correspondent aux filtres, 50 000 au plus, les plus récentes d’abord. Colonnes : `Date`, `Action`, `Libellé`, `Auteur`, `E-mail de l'auteur`, `Personne visée`, `Objet`, `Détails`, `Adresse IP`. L’export est lui-même inscrit au journal.

## Voir aussi

- [Utilisation et journal](https://realmoon.ai/documentation/organisations/utilisation-journal/), dans l’administration
- [Webhooks](https://realmoon.ai/documentation/api-organisations/webhooks/), pour recevoir les événements au fil de l’eau

---

Documentation Moon AI › API des organisations › Utilisation et journal. Page : https://realmoon.ai/documentation/api-organisations/utilisation-et-journal/. Modifiée le 5 novembre 2026.

© 2026 Stellarr Studio SAS. Tous droits réservés. Moon AI, Moon Blur et Stellarr Studio sont des marques déposées à l’INPI.