Obtenir l'usage par Key

GET /api/open/v1/usage/keys

Paramètres de requête

Paramètre	Emplacement	Type	Requis	Défaut	Description
start_timestamp	query	integer	Non	Voir ci-dessous	Date de début (incluse), secondes unix
end_timestamp	query	integer	Non	Voir ci-dessous	Date de fin (incluse), secondes unix
group_by	query	string	Non	key_name	Mode de regroupement : key_name regroupe par nom de Key au moment des requêtes, les Keys de même nom sont fusionnées sur une ligne ; key_id affiche une ligne par Key
key_id	query	integer	Non	—	Filtrer par ID de Key, entier positif ; répétez le paramètre ou séparez par des virgules pour plusieurs valeurs. Un ID appartenant à un autre utilisateur renvoie une liste vide
key_name	query	string	Non	—	Nom de Key exact au moment des requêtes ; répétez le paramètre pour plusieurs valeurs. Les virgules ne sont pas prises en charge car les noms peuvent en contenir
p	query	integer	Non	1	Numéro de page, de 1 à 1000000
page_size	query	integer	Non	10	Éléments par page, de 1 à 1000
sort_by	query	string	Non	total_tokens	Champ de tri : key_count (uniquement avec group_by=key_name), prompt_tokens, completion_tokens, total_tokens ou amount
order	query	string	Non	desc	Sens du tri : asc ou desc

Règles de plage temporelle :

• Les deux omis : les 30 derniers jours.
• Seulement start_timestamp : 30 jours vers l’avant, plafonné à l’heure actuelle.
• Seulement end_timestamp : 30 jours vers l’arrière.
• La plage peut couvrir au maximum 366 jours.

Chaque paramètre multi-valeurs accepte au maximum 50 valeurs ; au-delà, la réponse est 400 invalid_request. Un p / page_size fourni explicitement et invalide retourne 400 ; voir Pagination.

Exemple de requête

curl "https://www.routeapi.ai/api/open/v1/usage/keys?start_timestamp=1726400000&end_timestamp=1729000000&sort_by=total_tokens&order=desc&p=1&page_size=20" \
  -H "Authorization: Bearer $ROUTEAPI_MANAGEMENT_KEY"

Exemple de réponse

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_name": "bot",
        "key_count": 2,
        "prompt_tokens": 5000,
        "completion_tokens": 1000,
        "total_tokens": 6000,
        "amount": 0.20
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

Avec group_by=key_id, une ligne par Key, avec key_id et sans key_count :

{
  "success": true,
  "message": "",
  "data": {
    "items": [
      {
        "key_id": 12,
        "key_name": "bot",
        "prompt_tokens": 3000,
        "completion_tokens": 600,
        "total_tokens": 3600,
        "amount": 0.12
      },
      {
        "key_id": 15,
        "key_name": "bot",
        "prompt_tokens": 2000,
        "completion_tokens": 400,
        "total_tokens": 2400,
        "amount": 0.08
      }
    ],
    "total": 2,
    "page": 1,
    "page_size": 20,
    "start_timestamp": 1726400000,
    "end_timestamp": 1729000000
  }
}

Champs de réponse

Champ	Type	Description
items[].key_id	integer	Uniquement avec group_by=key_id. ID de la Key, utilisable dans Obtenir une API Key et d’autres endpoints ; 0 désigne l’usage sans API Key (par exemple le playground)
items[].key_name	string	group_by=key_name : nom de la Key au moment des requêtes. group_by=key_id : nom actuel de la Key ; si la Key n’existe plus ou si key_id vaut 0, le nom de sa dernière requête sur la plage est utilisé
items[].key_count	integer	Uniquement avec group_by=key_name. Nombre de Keys distinctes portant ce nom et ayant consommé sur la plage
items[].prompt_tokens	integer	Total des tokens d’entrée pour cette ligne
items[].completion_tokens	integer	Total des tokens de sortie pour cette ligne
items[].total_tokens	integer	Total des tokens d’entrée et de sortie
items[].amount	number	Montant consommé pour cette ligne (remboursements déduits), dans la devise du site, deux décimales
total	integer	Nombre total de lignes : nombre de noms avec group_by=key_name, nombre de Keys avec group_by=key_id (y compris la ligne où key_id vaut 0)
page	integer	Numéro de page courant
page_size	integer	Nombre effectif d’éléments par page
start_timestamp	integer	Date de début effective
end_timestamp	integer	Date de fin effective

Erreurs

HTTP	code	Scénario
400	invalid_request	group_by, sort_by ou order invalide, sort_by=key_count avec group_by=key_id, key_id qui n’est pas un entier positif, un timestamp qui n’est pas numérique ou est négatif, la plage invalide, les paramètres de pagination invalides, ou un paramètre multi-valeurs dépassant 50 valeurs
429	—	Limite de requêtes par utilisateur dépassée (30/minute par défaut) ; le corps peut être vide

Pour les autres codes d’erreur communs, voir Erreurs de l’API de la plateforme.

Remarques

• Les noms de Key peuvent se répéter : group_by=key_name fusionne les Keys de même nom sur une ligne, utilisez group_by=key_id pour les distinguer. Aucune valeur de Key n’est retournée.
• Les lignes sont d’abord triées par le champ sort_by, puis par key_name croissant (key_id croissant avec group_by=key_id) en cas d’égalité, la pagination est donc stable.
• L’historique conserve le nom de la Key au moment de la requête ; renommer une Key ne réécrit pas les enregistrements passés. Avec group_by=key_name, l’usage avant et après renommage forme donc deux lignes ; le filtre key_name correspond aussi au nom au moment de la requête, tandis que group_by=key_id renvoie le nom actuel, les deux peuvent donc différer.
• La somme des amount des lignes est égale au montant de Usage (hors erreurs d’arrondi).
• Le amount de chaque ligne est arrondi séparément ; la somme des lignes peut donc différer d’un total de jusqu’à 0,01.
• Seuls les logs de consommation (facturation) sont comptés ; les requêtes échouées sont exclues.
• Les nombres de tokens sont des comptes bruts, pas des millions.
• Les montants utilisent la devise d’affichage du site, voir Obtenir le solde.
• Pour exporter vers Excel, parcourez cet endpoint page par page avec les mêmes filtres et collectez les tableaux items.
• Cet endpoint partage la limite de requêtes par utilisateur (30/minute par défaut) avec Usage, Logs du compte, Exporter les logs et Usage par modèle. Voir Limites de débit.