> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sous-comptes : clés, limites et consommation par client final

> Donnez à chacun de vos clients ses propres clés d’API, sa limite de crédits et sa limite de concurrence, séparez leurs résultats et consultez la consommation de chacun. Vous recevez une seule facture.

Si vous utilisez querying.ai dans votre propre produit, créez un sous-compte par client. Un
sous-compte a ses propres clés d'API, limites, tâches, lots et moniteurs. Ses crédits sont pris sur
votre solde, et les endpoints de consommation indiquent combien facturer à chaque client.

## Fonctionnement d'un sous-compte

* **Ses propres clés et résultats.** Une clé de sous-compte soumet et lit tâches, lots et
  moniteurs comme n'importe quelle clé, et ne voit que son propre travail. Une tâche créée avec la clé d'Acme
  renvoie `404` à la clé de Globex et à vos propres clés.
* **Vos crédits.** Ses tâches sont facturées sur votre solde. Un sous-compte n'a pas de solde : ses clés
  reçoivent `403 SUB_ACCOUNT_FORBIDDEN` sur `GET /v1/credits` et `GET /v1/usage`.
* **Votre capacité.** La limite de concurrence de votre plan ou de votre contrat couvre vos propres tâches et
  celles de tous les sous-comptes ensemble : les sous-comptes n'ajoutent jamais de capacité. `GET /v1/async/status`
  compte cette file partagée avec votre clé, et la clé d'un sous-compte y reçoit `403 SUB_ACCOUNT_FORBIDDEN`.
* **Vos limites de moniteurs.** La limite `monitors` de `GET /v1/monitors/capabilities` compte
  vos moniteurs et ceux de tous les sous-comptes ensemble, et les limites `prompts` et `tasksPerRun`
  s'appliquent aux moniteurs d'un sous-compte comme aux vôtres.
* **Ses propres limites.** `monthlyCreditLimit` plafonne ce qui peut lui être facturé au cours d'un mois
  civil UTC. `concurrencyLimit` plafonne ses tâches en file et en cours à l'intérieur de votre limite. Les deux sont
  facultatives.
* **Un seul niveau.** Un sous-compte ne peut pas avoir de sous-comptes. Les e-mails d'alerte de ses moniteurs sont
  envoyés aux administrateurs de votre compte.

## Qui peut gérer les sous-comptes

Appelez les endpoints `/v1/sub-accounts` avec l'une de vos propres clés d'API, sans restriction de moteurs
ni limite de crédits quotidienne. Toute autre clé reçoit `403 SUB_ACCOUNT_FORBIDDEN`, car une clé restreinte
pourrait sinon émettre des clés sans ses propres restrictions. Les clés d'un sous-compte reçoivent la même
erreur.

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": {
    "code": "SUB_ACCOUNT_FORBIDDEN",
    "message": "Managing sub-accounts needs an API key without an engine scope or a daily credit limit",
    "timestamp": "2026-10-19T09:00:00.000Z"
  }
}
```

## Créer un sous-compte et une clé

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/sub-accounts \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme", "externalId": "cust_acme", "monthlyCreditLimit": 200000, "concurrencyLimit": 50}'
```

La réponse est `201` :

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "0199d2a4-5b10-7000-8000-000000000001",
    "name": "Acme",
    "externalId": "cust_acme",
    "status": "active",
    "monthlyCreditLimit": 200000,
    "concurrencyLimit": 50,
    "createdAt": "2026-10-09T09:00:00.000Z",
    "suspendedAt": null,
    "usage": { "month": "2026-10", "credits": 0, "tasks": 0, "reservedCredits": 0 }
  }
}
```

| Champ | Obligatoire | Description |
| - | - | - |
| `name` | Oui | 1 à 128 caractères. |
| `externalId` | Non | Votre identifiant pour ce client, 1 à 128 caractères, unique parmi vos sous-comptes. Une seconde création avec la même valeur renvoie `409 SUB_ACCOUNT_EXISTS` : une nouvelle tentative ne crée donc jamais de doublon. Retrouvez le sous-compte existant avec `GET /v1/sub-accounts?externalId=cust_acme`. |
| `monthlyCreditLimit` | Non | 0,01 à 20 000 000 crédits, au plus deux décimales. Omettez-le ou envoyez `null` pour ne fixer aucun plafond. |
| `concurrencyLimit` | Non | Entier de 1 à 100 000. Omettez-le ou envoyez `null` pour ne fixer aucun plafond. |

Tout autre champ renvoie `400 VALIDATION_ERROR` : une limite mal orthographiée ne laisse jamais un
client sans plafond.

Émettez ensuite une clé pour le sous-compte :

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID/keys \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production", "allowedTaskTypes": ["CHATGPT", "GEMINI"]}'
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "b7e4c1a2-...",
    "name": "production",
    "keyPrefix": "vt_3f9a1c2b",
    "createdAt": "2026-10-09T09:01:00.000Z",
    "allowedTaskTypes": ["CHATGPT", "GEMINI"],
    "dailyCreditLimit": null,
    "expiresAt": null,
    "key": "vt_3f9a1c2b..."
  }
}
```

> [!WARNING]
>
> `key` n'apparaît que dans cette réponse. Conservez-la maintenant ; elle ne sera plus jamais affichée.

Une clé accepte les mêmes réglages facultatifs qu'une clé du tableau de bord : `name` (1 à 64 caractères,
`default` par défaut), `allowedTaskTypes`, `dailyCreditLimit` et `expiresAt` (de 5 minutes à 2 ans
dans le futur). N'envoyez aucun corps pour une clé sans restriction.

Un sous-compte peut détenir jusqu'à 5 clés actives ; les clés révoquées et expirées ne comptent pas. Une sixième
renvoie `409 KEY_LIMIT`. Révoquez-en une d'abord.

La clé de votre client fonctionne sur tous les endpoints comme n'importe quelle autre clé :

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $ACME_KEY" \
  -H "Content-Type: application/json" \
  -d '{"taskType": "CHATGPT", "payload": {"prompt": "best project management software", "country": "US"}}'
```

## Gérer les clés

`GET /v1/sub-accounts/{id}/keys` liste toutes les clés que le sous-compte a eues, de la plus récente à la plus
ancienne, y compris les clés révoquées et expirées. Vérifiez `revokedAt` et `expiresAt` pour repérer les clés
actives.

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "keys": [
      {
        "id": "b7e4c1a2-...",
        "name": "production",
        "keyPrefix": "vt_3f9a1c2b",
        "createdAt": "2026-10-09T09:01:00.000Z",
        "revokedAt": null,
        "lastUsedAt": "2026-10-19T08:58:12.000Z",
        "allowedTaskTypes": ["CHATGPT", "GEMINI"],
        "dailyCreditLimit": null,
        "expiresAt": null
      },
      {
        "id": "4d2a9e10-...",
        "name": "staging",
        "keyPrefix": "vt_8c01d5e7",
        "createdAt": "2026-10-01T12:00:00.000Z",
        "revokedAt": "2026-10-09T09:02:00.000Z",
        "lastUsedAt": "2026-10-08T17:40:03.000Z",
        "allowedTaskTypes": [],
        "dailyCreditLimit": null,
        "expiresAt": null
      }
    ]
  }
}
```

`DELETE /v1/sub-accounts/{id}/keys/{keyId}` révoque une clé et renvoie
`{"success": true, "data": {"revoked": "<keyId>"}}`. Une clé déjà révoquée, ou qui n'appartient pas
au sous-compte, renvoie `404 NOT_FOUND`.

## Limites

| Limite | Compte | Quand elle est atteinte |
| - | - | - |
| `monthlyCreditLimit` | Ce qui a été facturé au sous-compte ce mois UTC, plus les crédits réservés par ses tâches encore en cours | `429 SUB_ACCOUNT_CREDIT_LIMIT` |
| `concurrencyLimit` | Les tâches en file et en cours du sous-compte | `429 PLAN_CONCURRENCY_LIMIT`, `details.source: "sub_account"` |
| La limite de votre plan ou contrat | Vos tâches et celles de tous les sous-comptes | `429 PLAN_CONCURRENCY_LIMIT`, `details.source: "plan"` ou `"contract"` |
| Votre solde | Tout le monde | `402 INSUFFICIENT_CREDITS` |

Seul le sous-compte qui a atteint sa propre limite est refusé ; vos autres clients continuent de
fonctionner. Une limite relevée s'applique dès la requête suivante.

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": {
    "code": "SUB_ACCOUNT_CREDIT_LIMIT",
    "message": "Sub-account monthly credit limit 200000 would be exceeded (199998 used, 3 needed)",
    "details": { "limit": 200000, "used": 199998, "needed": 3, "retryAfterSec": 1814400 },
    "timestamp": "2026-10-09T09:00:00.000Z"
  }
}
```

`retryAfterSec` compte jusqu'au début du mois UTC suivant, quand le décompte mensuel repart
de zéro. Voir [Crédits et limites](/fr/concepts/credits-and-limits.md) pour les limites de l'ensemble du compte.

## Consulter un sous-compte maintenant

`GET /v1/sub-accounts/{id}` renvoie le sous-compte avec la consommation du mois et
`activeTasks`, le nombre de ses tâches en file ou en cours à cet instant. Comparez-le à
`concurrencyLimit` pour voir à quel point le client est proche de son plafond.

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "0199d2a4-5b10-7000-8000-000000000001",
    "name": "Acme",
    "externalId": "cust_acme",
    "status": "active",
    "monthlyCreditLimit": 200000,
    "concurrencyLimit": 50,
    "createdAt": "2026-10-09T09:00:00.000Z",
    "suspendedAt": null,
    "usage": { "month": "2026-10", "credits": 48211.5, "tasks": 39870, "reservedCredits": 37.5 },
    "activeTasks": 31
  }
}
```

Les valeurs ci-dessus sont un exemple. Dans `usage`, `credits` et `tasks` correspondent à ce qui a été facturé ce
mois UTC, et `reservedCredits` aux crédits réservés par les tâches encore en cours.

## Consommation et facturation

Chaque facturation apparaît aussi dans votre propre relevé de facturation ; ces endpoints la répartissent par client.
Les tâches en échec ne sont jamais facturées et ne comptent jamais. Les montants en crédits comportent jusqu'à deux décimales.

* `GET /v1/sub-accounts` liste vos sous-comptes, du plus ancien au plus récent, chacun avec le `usage` du
  mois. Paginez avec `limit` (100 par défaut, au plus 1 000) et renvoyez `nextCursor` comme
  `cursor`.
* `GET /v1/sub-accounts/usage` totalise chaque sous-compte sur une plage de dates UTC.
* `GET /v1/sub-accounts/{id}/usage` donne les facturations d'un sous-compte par jour et par moteur.

Les deux endpoints de consommation acceptent `from` et `to` au format `YYYY-MM-DD`, bornes incluses. `from` vaut par défaut le
premier jour du mois UTC en cours et `to` aujourd'hui ; une plage couvre au plus 366 jours.

### Tous les sous-comptes

```bash theme={"theme":"css-variables"}
curl "https://api.querying.ai/v1/sub-accounts/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

Par exemple :

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "from": "2026-10-01",
    "to": "2026-10-31",
    "credits": 184200,
    "tasks": 61400,
    "subAccounts": [
      { "id": "0199d2a4-5b10-7000-8000-000000000001", "name": "Acme", "externalId": "cust_acme", "credits": 150000, "tasks": 50000 },
      { "id": "0199d2a4-6c20-7000-8000-000000000002", "name": "Globex", "externalId": "cust_globex", "credits": 34200, "tasks": 11400 }
    ]
  }
}
```

Les sous-comptes sont listés du plus consommateur au moins consommateur. Un sous-compte sans facturation sur la plage
est omis.

### Un sous-compte

```bash theme={"theme":"css-variables"}
curl "https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID/usage?from=2026-10-08&to=2026-10-09" \
  -H "Authorization: Bearer $QUERYING_API_KEY"
```

Par exemple :

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "0199d2a4-5b10-7000-8000-000000000001",
    "from": "2026-10-08",
    "to": "2026-10-09",
    "credits": 3062.5,
    "tasks": 2950,
    "days": [
      { "date": "2026-10-08", "taskType": "CHATGPT", "credits": 1500, "tasks": 1500 },
      { "date": "2026-10-08", "taskType": "GEMINI", "credits": 312.5, "tasks": 250 },
      { "date": "2026-10-08", "taskType": "OTHER", "credits": 50, "tasks": 0 },
      { "date": "2026-10-09", "taskType": "CHATGPT", "credits": 1200, "tasks": 1200 }
    ]
  }
}
```

* `credits` et `tasks` au premier niveau sont les totaux de `days`.
* `days` contient une ligne par date UTC et par moteur ayant eu une facturation, triée par date, puis par
  `taskType`. Les jours sans facturation n'ont pas de ligne.
* `taskType: "OTHER"` est une facturation qui n'est pas une tâche, comme la
  [lecture des concurrents](/fr/monitors.md#coût-et-calendrier) d'un moniteur. Elle ajoute des crédits mais aucune `tasks`.

## Suspendre et réactiver

```bash theme={"theme":"css-variables"}
curl -X PATCH https://api.querying.ai/v1/sub-accounts/$SUB_ACCOUNT_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "suspended"}'
```

* Ses clés renvoient `401` en moins de cinq secondes.
* Ses moniteurs cessent de s'exécuter, et les éléments de lot non démarrés se terminent en
  `API_KEY_INACTIVE`.
* Les tâches déjà en file ou en cours se terminent et sont facturées.

`{"status": "active"}` rétablit ses clés et ses moniteurs. Chaque moniteur s'exécute une fois à son retour
au lieu de rattraper les exécutions manquées. Le même `PATCH` modifie `name`, `externalId`,
`monthlyCreditLimit` et `concurrencyLimit` ; `null` supprime une limite ou l'`externalId`. Un
sous-compte ne peut pas être supprimé ; suspendez-le plutôt.

## Erreurs

| Statut | Code | Cause |
| - | - | - |
| `400` | `VALIDATION_ERROR` | JSON invalide, champ inconnu, valeur hors limites ou plage de consommation incorrecte. |
| `403` | `SUB_ACCOUNT_FORBIDDEN` | La clé est restreinte à certains moteurs ou a une limite de crédits quotidienne, ou appartient à un sous-compte. |
| `404` | `NOT_FOUND` | Aucun de vos sous-comptes n'a cet id, ou aucune clé active n'a cet id. |
| `409` | `SUB_ACCOUNT_EXISTS` | Un autre sous-compte a déjà cet `externalId`. |
| `409` | `KEY_LIMIT` | Le sous-compte a déjà 5 clés actives. |

## Endpoints

| Méthode et chemin | Usage |
| - | - |
| [`POST /v1/sub-accounts`](/fr/api-reference/sub-accounts/create-sub-account) | Créer |
| [`GET /v1/sub-accounts`](/fr/api-reference/sub-accounts/list-sub-accounts) | Lister, avec `externalId`, `limit` et `cursor` |
| [`GET /v1/sub-accounts/{id}`](/fr/api-reference/sub-accounts/get-sub-account) | Un sous-compte, avec `activeTasks` |
| [`PATCH /v1/sub-accounts/{id}`](/fr/api-reference/sub-accounts/update-sub-account) | Modifier les réglages, suspendre ou réactiver |
| [`GET /v1/sub-accounts/usage`](/fr/api-reference/sub-accounts/list-usage) | Totaux par sous-compte |
| [`GET /v1/sub-accounts/{id}/usage`](/fr/api-reference/sub-accounts/get-usage) | Un sous-compte par jour et par moteur |
| [`GET /v1/sub-accounts/{id}/keys`](/fr/api-reference/sub-accounts/list-keys) | Lister ses clés, y compris révoquées et expirées |
| [`POST /v1/sub-accounts/{id}/keys`](/fr/api-reference/sub-accounts/issue-key) | Émettre une clé |
| [`DELETE /v1/sub-accounts/{id}/keys/{keyId}`](/fr/api-reference/sub-accounts/revoke-key) | Révoquer une clé |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.