Obtenir l’usage d’une API Key

Vue d’ensemble

Cet endpoint renvoie les détails d’usage au niveau de la clé sans exposer les métadonnées de routage physique.

Paramètres de requête

Paramètre	Type	Valeurs par défaut / limites	Description
`page`	integer	valeur par défaut `1`, min. `1`	Numéro de page à partir de 1
`limit`	integer	valeur par défaut `50`, min. `1`, max. `100`	Nombre d’éléments par page
`model`	string	longueur maximale `100`	Nom du modèle demandé
`modelVendor`	string	longueur maximale `100`	Fournisseur public du modèle
`scene`	enum	-	`chat`, `image`, `audio`, `video`, `embedding`, `rerank`, `translation`, `music`, `3d`, `realtime`
`startDate`	string	-	Borne inférieure incluse ; accepte RFC3339 avec fuseau horaire ou `YYYY-MM-DD`
`endDate`	string	-	Borne supérieure incluse ; accepte RFC3339 avec fuseau horaire ou `YYYY-MM-DD`

Si startDate et endDate sont fournis ensemble, startDate doit être antérieur ou égal à endDate.

Notes

Les champs monétaires prennent uniquement en charge l’USD.
La réponse est paginée.
La réponse ne contient que des champs publics de billing et de reporting.
Une ligne d’usage peut aussi inclure billing_transaction_id une fois que la requête sous-jacente a été réglée. Utilisez-le avec request_id pour le rapprochement au niveau de la requête.
Les métadonnées de routage interne et de canaux physiques restent masquées.

Exemple

Requête

cURL

curl "https://api.tokenlab.sh/v1/management/api-keys/key_abc123def456/usage?page=1&limit=20&scene=chat&startDate=2026-07-01&endDate=2026-07-31" \
  -H "Authorization: Bearer mt-your-management-token"

Cette page fournit le schéma OpenAPI et des exemples de requêtes à copier. Envoyez les requêtes de gestion depuis votre terminal ou votre client avec un Management Token ; l’envoi direct n’est pas disponible sur cette page.

Exemple de réponse

Réponse

200 OK

{
  "api_key": {
    "id": "key_abc123def456",
    "name": "Backend Worker",
    "key_prefix": "sk-live...",
    "status": "active",
    "limit_amount": 500,
    "limit_amount_decimal": "500",
    "used_amount": 148.25,
    "used_amount_decimal": "148.25",
    "models": [
      "gpt-5.6-luna",
      "claude-3-7-sonnet"
    ],
    "expires_at": "2026-12-31T23:59:59.000Z",
    "last_used_at": "2026-07-08T03:12:45.000Z",
    "created_at": "2026-07-01T10:00:00.000Z",
    "delivery_policy": null
  },
  "items": [
    {
      "request_id": "req_abc123",
      "billing_transaction_id": "billtxn_abc123",
      "model": "gpt-5.6-luna",
      "logical_model": "gpt-5.6-luna",
      "model_vendor": "OpenAI",
      "scene": "chat",
      "usage_unit": "per_token",
      "usage_quantity": 1500,
      "usage_quantity_decimal": "1500",
      "prompt_tokens": 1000,
      "completion_tokens": 500,
      "total_tokens": 1500,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "cache_write_tokens_5m": 0,
      "cache_write_tokens_1h": 0,
      "cost": 0.0012,
      "cost_decimal": "0.0012",
      "created_at": "2026-07-08T03:15:00.000Z",
      "requested_policy": null,
      "resolved_tier": null,
      "charged_price_basis": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  },
  "summary": {
    "total_requests": 1,
    "total_cost": 0.0012,
    "total_cost_decimal": "0.0012",
    "total_prompt_tokens": 1000,
    "total_completion_tokens": 500,
    "total_tokens": 1500,
    "usage_unit_breakdown": [
      {
        "usage_unit": "per_token",
        "usage_quantity": 1500
      }
    ]
  },
  "breakdowns": {
    "by_model": [
      {
        "model": "gpt-5.6-luna",
        "logical_model": "gpt-5.6-luna",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_logical_model": [
      {
        "model": "gpt-5.6-luna",
        "logical_model": "gpt-5.6-luna",
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012",
        "usage_quantity": 1500,
        "usage_quantity_decimal": "1500"
      }
    ],
    "by_model_vendor": [
      {
        "model_vendor": "OpenAI",
        "requests": 1,
        "cost": 0.0012
      }
    ],
    "by_scene": [
      {
        "scene": "chat",
        "requests": 1,
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ],
    "daily_cost": [
      {
        "date": "2026-07-08T00:00:00.000Z",
        "cost": 0.0012,
        "cost_decimal": "0.0012"
      }
    ]
  }
}

Champs importants

api_keyobject

Résumé de la clé API utilisant les mêmes champs que les réponses de liste, de création et de mise à jour.

itemsarray

Lignes d’utilisation paginées.

paginationobject

Métadonnées de pagination contenant page, limit, total et totalPages.

summaryobject

Totaux agrégés pour les filtres sélectionnés.

breakdownsobject

Ventilations agrégées pour les filtres sélectionnés.

items[].request_idstring | null

Identifiant de requête public pour l’assistance et le rapprochement.

items[].billing_transaction_idstring | null

Identifiant de transaction de facturation réglée, lorsqu’il est disponible.

items[].modelstring

Nom du modèle public demandé.

items[].logical_modelstring

Modèle public logique utilisé pour les rapports.

items[].model_vendorstring | null

Fournisseur du modèle public.

items[].scenestring | null

Scène de requête publique.

items[].usage_unitstring

Unité d’utilisation facturée, telle que per_token.

items[].usage_quantitynumber

Quantité d’utilisation renvoyée sous forme de nombre JSON pour l’affichage.

items[].usage_quantity_decimalstring

Quantité d’utilisation exacte renvoyée sous forme de chaîne décimale.

items[].prompt_tokensnumber

Nombre de tokens de prompt.

items[].completion_tokensnumber

Nombre de tokens de complétion.

items[].total_tokensnumber

Nombre total de tokens.

items[].cache_read_tokensnumber

Nombre de tokens lus dans le cache.

items[].cache_write_tokensnumber

Nombre total de tokens écrits dans le cache.

items[].cache_write_tokens_5mnumber

Nombre de tokens d’écriture du cache sur cinq minutes.

items[].cache_write_tokens_1hnumber

Nombre de tokens d’écriture du cache sur une heure.

items[].costnumber

Coût en USD renvoyé sous forme de nombre JSON pour l’affichage.

items[].cost_decimalstring

Coût exact en USD renvoyé sous forme de chaîne décimale.

items[].requested_policystring | null

auto, verified, official, null. Politique de livraison demandée, si enregistrée.

items[].resolved_tierstring | null

verified, official, null. Niveau de livraison utilisé, si enregistré.

items[].charged_price_basisobject | null

Prix appliqué et quantité facturable, si enregistrés.

items[].created_atstring

Horodatage ISO de la ligne d’utilisation.

summary.total_requestsnumber

Nombre total de requêtes.

summary.total_costnumber

Coût total en USD renvoyé sous forme de nombre JSON pour l’affichage.

summary.total_cost_decimalstring

Coût total exact en USD renvoyé sous forme de chaîne décimale.

summary.total_prompt_tokensnumber

Nombre total de tokens de prompt.

summary.total_completion_tokensnumber

Nombre total de tokens de complétion.

summary.total_tokensnumber

Nombre total de tokens.

summary.usage_unit_breakdownarray

Quantité d’utilisation regroupée par unité d’utilisation.

breakdowns.by_modelarray

Ventilation par modèle public demandé.

breakdowns.by_logical_modelarray

Ventilation par modèle public logique.

breakdowns.by_model_vendorarray

Ventilation par fournisseur de modèle public.

breakdowns.by_scenearray

Ventilation par scène de requête publique.

breakdowns.daily_costarray

Évolution quotidienne des coûts.

Autorisation

ManagementTokenAuth

AuthorizationBearer <token>

Authentification par jeton de gestion. Créez ou gérez vos jetons de gestion dans Dashboard > API > Management Tokens.

Emplacement: header

Paramètres de chemin

keyId*string

Paramètres de requête

page?integer

Numéro de page commençant à 1. La valeur par défaut est 1.

Plage1 <= value

par défaut1

limit?integer

Taille de la page. La valeur par défaut est 50 et le maximum est 100.

Plage1 <= value <= 100

par défaut50

model?string

Filtrer par nom de modèle demandé. Longueur maximale 100.

Longueurlength <= 100

modelVendor?string

Filtrer par fournisseur de modèle public. Longueur maximale 100.

Longueurlength <= 100

scene?string

Filtrer par scène de requête publique.

Valeurs possibles

"chat"
"image"
"audio"
"video"
"embedding"
"rerank"
"translation"
"music"
"3d"
"realtime"
"systemone"

startDate?string

Filtre de date inclusif. Accepte soit le format RFC3339 avec fuseau horaire (par exemple 2026-03-28T00:00:00+08:00) ou YYYY-MM-DD.

endDate?string

Filtre de date inclusif. Accepte soit le format RFC3339 avec fuseau horaire (par exemple 2026-03-28T00:00:00+08:00) ou YYYY-MM-DD.

Obtenir l’usage d’une API Key

Vue d’ensemble

Paramètres de requête

Notes

Exemple

Requête / Réponse

Exemple de réponse

Champs importants

Autorisation

Paramètres de chemin

Paramètres de requête

Réponse

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Obtenir l’usage d’une API Key

Vue d’ensembleCopy Anchor Link

Paramètres de requêteCopy Anchor Link

NotesCopy Anchor Link

ExempleCopy Anchor Link

Requête / RéponseCopy Anchor Link

Exemple de réponseCopy Anchor Link

Champs importantsCopy Anchor Link

AutorisationCopy Anchor Link

Paramètres de cheminCopy Anchor Link

Paramètres de requêteCopy Anchor Link

RéponseCopy Anchor Link

200application/json

400application/json

401application/json

403application/json

404application/json

Vue d’ensemble

Paramètres de requête

Notes

Exemple

Requête / Réponse

Exemple de réponse

Champs importants

Autorisation

Paramètres de chemin

Paramètres de requête

Réponse

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`