> ## 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 enregistrements d’appels d’API de la plateforme AceDataCloud

> Platform API guide - Ace Data Cloud

Interrogez les détails des appels d’API métier du compte actuel au cours des 60 derniers jours, adapté à la vérification de la facturation, à l’identification des requêtes échouées, ainsi qu’au diagnostic des problèmes par service, Application, API ou identifiant.

> Cette page interroge les journaux d’appels propres au compte. Si vous souhaitez uniquement consulter les statistiques publiques d’appels d’une API sur l’ensemble de la plateforme, utilisez les [statistiques d’appels d’API](https://platform.acedata.cloud/documents/platform-api-usage).

## Préparatifs

### 1. Créer un jeton de compte

Cette interface appartient aux API de gestion de plateforme et nécessite l’utilisation d’un **Account Token (jeton de compte)** :

1. Connectez-vous à la [plateforme AceDataCloud](https://platform.acedata.cloud).
2. Ouvrez la [console Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. Cliquez sur « Créer », puis enregistrez immédiatement le jeton dans votre gestionnaire de mots de passe ou Secret Manager.

Pour les instructions complètes, consultez [Gérer les jetons de compte de la plateforme AceDataCloud](https://platform.acedata.cloud/documents/platform-token). Les jetons de compte sont utilisés pour `platform.acedata.cloud/api/v1/**` ; les interfaces métier `api.acedata.cloud/**` utilisent des identifiants d’API (Credential), et les deux ne peuvent pas être utilisés de manière interchangeable.

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

N’écrivez pas le jeton dans le code frontend, les journaux ou les dépôts publics ; s’il est divulgué, supprimez-le immédiatement dans la console et recréez-en un.

### 2. Préparer les ID de filtrage (facultatif)

Vous pouvez consulter les enregistrements auxquels le compte actuel a accès sans transmettre de conditions de filtrage. Pour réduire le périmètre :

* `application_id` : obtenez-le depuis la [liste des demandes de service](https://platform.acedata.cloud/documents/platform-application-list) ;
* `credential_id` : obtenez-le depuis la [liste des identifiants d’API](https://platform.acedata.cloud/documents/platform-credential-list) ;
* `api_id` : obtenez-le depuis la [liste des API](https://platform.acedata.cloud/documents/platform-api-list) ;
* `service_id` : obtenez-le depuis la [liste des services](https://platform.acedata.cloud/documents/platform-service-list).

Les utilisateurs ordinaires n’ont pas besoin de transmettre `user_id` ; s’il est transmis explicitement, il doit correspondre au compte actuel, sinon `403` est retourné. Les administrateurs peuvent utiliser ce paramètre pour filtrer entre les comptes.

## Vue d’ensemble de l’interface

| Élément | Contenu |
| - | - |
| Méthode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| Authentification | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` peuvent l’inclure par extension) |
| Pagination | `count` + `items`, 10 éléments par page par défaut |

## Périmètre de requête

| `perspective` | Signification |
| - | - |
| `both` | Valeur par défaut ; retourne les enregistrements payés ou réellement appelés par le compte actuel |
| `billing` | Retourne uniquement les enregistrements payés par le compte actuel |
| `actor` | Retourne uniquement les enregistrements réellement appelés par le compte actuel |

## Paramètres de requête

| Paramètre | Type | Obligatoire | Par défaut | Description |
| - | - | - | - | - |
| `perspective` | string | Non | `both` | `billing`, `actor` ou `both` |
| `user_id` | UUID | Non | — | Filtrage par utilisateur réservé aux administrateurs ; prend en charge les paramètres répétés |
| `service_id` | UUID | Non | — | Filtrage par service ; prend en charge les paramètres répétés |
| `application_id` | UUID | Non | — | Filtrage par Application ; prend en charge les paramètres répétés |
| `api_id` | UUID | Non | — | Filtrage par API ; prend en charge les paramètres répétés |
| `credential_id` | UUID | Non | — | Filtrage par identifiant d’API ; prend en charge les paramètres répétés |
| `status_code` | integer | Non | — | Filtrage par code d’état HTTP ; prend en charge les valeurs répétées ou séparées par des virgules |
| `created_at_from` | datetime | Non | — | Limite inférieure de l’heure de création, ISO 8601 |
| `created_at_to` | datetime | Non | — | Limite supérieure de l’heure de création, ISO 8601 |
| `limit` | integer | Non | 10 | Nombre d’éléments par page, maximum 100 |
| `offset` | integer | Non | 0 | Décalage de pagination |
| `ordering` | string | Non | `-created_at` | Tri décroissant par heure de création |

Lorsque l’heure de la requête est antérieure aux 60 derniers jours, l’interface retourne une erreur de validation de champ `400`, indiquant que les détails complets des appels ne sont conservés que pendant 60 jours.

## Exemples de requêtes

Interroger les 100 enregistrements les plus récents :

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Filtrer par heure, Application et statut d’échec :

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

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-02T00:00:00Z' \
  --data-urlencode 'status_code=500' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Exemple de pagination Python :

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

url = "https://platform.acedata.cloud/api/v1/usage/apis/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {"perspective": "both", "limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["status_code"], usage["deducted_amount"], usage["trace_id"])

if params["offset"] + len(data["items"]) < data["count"]:
    params["offset"] += len(data["items"])
```

## Exemple de réponse

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": "00000000-0000-4000-8000-000000000002",
      "application_id": "00000000-0000-4000-8000-000000000003",
      "api_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": "00000000-0000-4000-8000-000000000005",
      "trace_id": "example-trace-id",
      "status_code": 200,
      "used_amount": 1.25,
      "original_amount": 1.25,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "started_at": "2026-09-01T08:00:00Z",
      "finished_at": "2026-09-01T08:00:01Z",
      "elapsed": 1.0,
      "created_at": "2026-09-01T08:00:01Z",
      "updated_at": "2026-09-01T08:00:01Z",
      "metadata": {"model": "example-model"},
      "api": {"title": "Example API"},
      "service": {"id": "00000000-0000-4000-8000-000000000006", "title": "Example Service"},
      "credential": {"id": "00000000-0000-4000-8000-000000000005", "name": "Production"}
    }
  ]
}
```

## Champs clés

| Champ | Description |
| - | - |
| `user_id` | Compte auquel cette facturation est imputée |
| `actor_user_id` | Compte qui a effectivement initié l’appel ; il peut différer de `user_id` lorsqu’un tiers est autorisé à utiliser les identifiants |
| `used_amount` | Consommation de cet appel calculée selon les règles d’origine |
| `original_amount` | Consommation d’origine avant la remise de l’application |
| `deducted_amount` | Quota finalement réellement déduit |
| `remaining_amount` | Quota restant de l’Application après la finalisation de cette facturation |
| `elapsed` | Durée de l’appel enregistrée côté serveur, en secondes |
| `trace_id` | Identifiant de suivi utilisé lors de l’analyse d’une requête unique |
| `metadata` | Métadonnées publiques ; la liste ne renvoie pas le contenu complet de la requête ou de la réponse |
| `api` / `service` / `credential` | Résumé des objets associés pour faciliter l’affichage ; peut être vide lorsque l’objet associé n’existe plus |

L’unité de quota est déterminée par le `service.unit` de l’Application correspondante et ne doit pas être considérée comme des dollars par défaut.

## Erreurs et nouvelles tentatives

| HTTP | `error` | Signification | Méthode de traitement |
| - | - | - | - |
| 400 | Erreur de validation de champ | La plage de requête est antérieure à la période de conservation de 60 jours | Ajustez l’heure de début pour qu’elle soit comprise dans les 60 derniers jours |
| 401 | `not_authenticated` | Jeton de compte absent ou non valide | Vérifiez l’Account Token, n’utilisez pas par erreur le Credential métier |
| 403 | `permission_denied` | La requête inclut des enregistrements que vous n’êtes pas autorisé à consulter | Supprimez les conditions de filtrage des utilisateurs non autorisés |
| 429 | `usage_query_in_progress` | Une requête exactement identique est toujours en cours d’exécution | Attendez `Retry-After`, puis réessayez avec un délai d’attente progressif |
| 503 | `usage_query_timeout` | La requête dépasse le délai de sécurité côté serveur | Réessayez après avoir réduit la plage temporelle ou ajouté des conditions de filtrage |

Un seul appel en cours est autorisé au maximum pour le même ensemble de paramètres de requête. Pour les requêtes étendues, utilisez en priorité une fenêtre d’un jour ou moins ; n’empilez pas des requêtes identiques à intervalles fixes.

## Étapes suivantes

* [Agrégation du volume d’appels](https://platform.acedata.cloud/documents/platform-usage-aggregate) : consultez l’utilisation agrégée par date et par API.
* [Exportation du volume d’appels](https://platform.acedata.cloud/documents/platform-usage-export) : téléchargez directement un grand nombre de détails au format CSV.
* [Consulter les enregistrements d’appels Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage) : interrogez les enregistrements des services de type Proxy.
* [Consulter les détails de la demande de service](https://platform.acedata.cloud/documents/platform-application-detail) : vérifiez le solde et l’unité de quota.
* [Renouveler les identifiants API](https://platform.acedata.cloud/documents/platform-credential-rotate) : remplacez-les immédiatement en cas de suspicion de fuite des identifiants.


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