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

# Obtenir les statistiques agrégées des appels API de la plateforme AceDataCloud

> Platform API guide - Ace Data Cloud

Agrège le nombre de requêtes et le quota réellement déduit du compte actuel par date et par API, adapté à la création de rapports mensuels, de graphiques de tendances et d'analyses de coûts. Utilisez la [liste des enregistrements d'appels](https://platform.acedata.cloud/documents/platform-usage-list) lorsqu'un dépannage élément par élément est nécessaire, et utilisez l'[export des volumes d'appels](https://platform.acedata.cloud/documents/platform-usage-export) lorsqu'un détail hors ligne complet est nécessaire.

## Préparation

1. Connectez-vous à la [plateforme AceDataCloud](https://platform.acedata.cloud).
2. Créez un jeton de compte dans la [console Account Token](https://platform.acedata.cloud/console/platform-tokens), et enregistrez-le immédiatement.
3. Si vous devez réduire le périmètre, obtenez les ID correspondants depuis la [liste des demandes de service](https://platform.acedata.cloud/documents/platform-application-list), la [liste des identifiants API](https://platform.acedata.cloud/documents/platform-credential-list) ou la [liste des API](https://platform.acedata.cloud/documents/platform-api-list).

Pour une description complète des jetons, consultez [Gérer les jetons de compte](https://platform.acedata.cloud/documents/platform-token). Cette interface utilise un Account Token et n'utilise pas de Credential métier.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

## Aperçu de l'interface

| Élément | Contenu |
| - | - |
| Méthode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Authentification | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`（`platform:read` / `platform` peut l'inclure） |
| Périmètre des autorisations | Pour les utilisateurs ordinaires, limité à leur propre consommation payante ; les administrateurs peuvent transmettre `user_id` |

## Paramètres de requête

| Paramètre | Type | Obligatoire | Par défaut | Description |
| - | - | - | - | - |
| `created_at_from` | date / datetime | Non | Premier jour du mois en cours dans le fuseau horaire sélectionné | Heure de début, nom de paramètre recommandé |
| `created_at_to` | date / datetime | Non | Heure actuelle | Heure de fin, nom de paramètre recommandé |
| `timezone` | string | Non | `UTC` | Fuseau horaire IANA, par exemple `Asia/Shanghai` ; les valeurs non valides reviennent à UTC |
| `service_id` | UUID | Non | — | Filtrer par service ; prend en charge les paramètres répétés |
| `application_id` | UUID | Non | — | Filtrer par Application ; prend en charge les paramètres répétés |
| `api_id` | UUID | Non | — | Filtrer par API ; prend en charge les paramètres répétés |
| `credential_id` | UUID | Non | — | Filtrer par identifiant API ; prend en charge les paramètres répétés |
| `include_models` | boolean | Non | `false` | Indique s'il faut calculer en plus l'agrégation par dimension de modèle ; augmente le coût de la requête |
| `user_id` | UUID | Non | Pour les utilisateurs ordinaires, limité à eux-mêmes ; pour les administrateurs, tous les comptes si non transmis | Seuls les administrateurs peuvent spécifier n'importe quel compte |

`start_time` / `end_time` peuvent toujours être utilisés comme alias de compatibilité pour les anciens clients ; pour les nouvelles intégrations, utilisez uniformément `created_at_from` / `created_at_to`. La forme date de `created_at_to` inclura ce jour calendaire, c'est-à-dire que minuit du jour suivant est utilisé comme limite.

## Exemples de requêtes

Interrogez l'agrégation quotidienne/API du mois en cours à l'heure de Pékin, avec la dimension de modèle incluse :

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Interrogez la consommation d'une semaine pour une Application spécifiée :

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Exemple Python :

```python theme={null}
import os
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## Exemple de réponse

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## Champs de réponse

| Champ | Description |
| - | - |
| `items` | Groupé par date dans le fuseau horaire sélectionné et par `api_id` ; chaque ligne contient `date`, `api_id`, `amount` |
| `total` | Somme de `deducted_amount` dans le périmètre de requête |
| `apis` | Mappage de l'ID API vers le résumé du titre, pour faciliter l'affichage de `items` |
| `requests` | Nombre total de requêtes dans le périmètre de requête |
| `models` | Calculé uniquement lorsque `include_models=true` ; chaque élément contient `model`, `amount`, `requests` |

L'unité de quota dépend de `service.unit` de l'Application concernée. Si la requête comprend des services avec différentes unités, effectuez d'abord des statistiques séparées par `service_id` ou `application_id`, afin d'éviter les comparaisons ou additions directes.

Lorsque l'heure de fin n'est pas supérieure à l'heure de début, l'interface renvoie une structure vide complète : `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Erreurs et recommandations de performance

| HTTP | `error` | Méthode de traitement |
| - | - | - |
| 400 | `usage_history_expired` | Ajustez la plage horaire après `available_from` dans la réponse |
| 401 | `not_authenticated` | Vérifiez l'Account Token, n'utilisez pas par erreur un Credential métier |
| 403 | `permission_denied` | Les utilisateurs ordinaires ne peuvent pas interroger d'autres comptes |

* N'activez pas `include_models` par défaut ; activez-le uniquement lorsque le rapport nécessite réellement une répartition par modèle.
* Pour les requêtes sur de grandes plages, séparez en priorité par `service_id` ou `application_id`, afin d'éviter le mélange d'unités et de réduire le coût des requêtes.
* Les dates sans appels ne sont pas automatiquement complétées par zéro ; le client doit compléter l'axe des dates avant de tracer le graphique.

## Étape suivante

* [Consulter les enregistrements d’appels](https://platform.acedata.cloud/documents/platform-usage-list) : localiser les détails qui constituent le résultat agrégé.
* [Exporter le volume d’appels](https://platform.acedata.cloud/documents/platform-usage-export) : télécharger les détails complets au format CSV.
* [Consulter les détails de la demande de service](https://platform.acedata.cloud/documents/platform-application-detail) : confirmer le solde et l’unité.


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