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

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.

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

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 :

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

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"]}'

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

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é :

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.

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

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

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

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 :

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

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 :

{
  "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 d’un moniteur. Elle ajoute des crédits mais aucune tasks.

Suspendre et réactiver

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`	Créer
`GET /v1/sub-accounts`	Lister, avec `externalId`, `limit` et `cursor`
`GET /v1/sub-accounts/{id}`	Un sous-compte, avec `activeTasks`
`PATCH /v1/sub-accounts/{id}`	Modifier les réglages, suspendre ou réactiver
`GET /v1/sub-accounts/usage`	Totaux par sous-compte
`GET /v1/sub-accounts/{id}/usage`	Un sous-compte par jour et par moteur
`GET /v1/sub-accounts/{id}/keys`	Lister ses clés, y compris révoquées et expirées
`POST /v1/sub-accounts/{id}/keys`	Émettre une clé
`DELETE /v1/sub-accounts/{id}/keys/{keyId}`	Révoquer une clé

Premiers pas

Concepts clés

Moteurs de réponse

Recherche et données web

Options de requête

Analyses

Suivi GEO

Compte et données

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

Fonctionnement d’un sous-compte

Qui peut gérer les sous-comptes

Créer un sous-compte et une clé

Gérer les clés

Limites

Consulter un sous-compte maintenant

Consommation et facturation

Tous les sous-comptes

Un sous-compte

Suspendre et réactiver

Erreurs

Endpoints

​Fonctionnement d’un sous-compte

​Qui peut gérer les sous-comptes

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

​Gérer les clés

​Limites

​Consulter un sous-compte maintenant

​Consommation et facturation

​Tous les sous-comptes

​Un sous-compte

​Suspendre et réactiver

​Erreurs

​Endpoints

Fonctionnement d’un sous-compte

Qui peut gérer les sous-comptes

Créer un sous-compte et une clé

Gérer les clés

Limites

Consulter un sous-compte maintenant

Consommation et facturation

Tous les sous-comptes

Un sous-compte

Suspendre et réactiver

Erreurs

Endpoints