> ## 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.

# Ottenere statistiche aggregate sul volume di chiamate API della piattaforma AceDataCloud

> Platform API guide - Ace Data Cloud

Aggrega per data e API il numero di richieste e l'importo effettivamente detratto dell'account corrente, adatto per creare report mensili, grafici delle tendenze e analisi dei costi. Quando è necessario risolvere gli errori voce per voce, utilizzare l'[elenco dei record delle chiamate](https://platform.acedata.cloud/documents/platform-usage-list); quando sono necessari dettagli offline completi, utilizzare l'[esportazione del volume di chiamate](https://platform.acedata.cloud/documents/platform-usage-export).

## Preparazione

1. Accedere alla [piattaforma AceDataCloud](https://platform.acedata.cloud).
2. Creare un token dell'account nella [console Account Token](https://platform.acedata.cloud/console/platform-tokens) e salvarlo immediatamente.
3. Se è necessario restringere l'ambito, ottenere gli ID corrispondenti dall'[elenco delle richieste di servizio](https://platform.acedata.cloud/documents/platform-application-list), dall'[elenco delle credenziali API](https://platform.acedata.cloud/documents/platform-credential-list) o dall'[elenco delle API](https://platform.acedata.cloud/documents/platform-api-list).

Per la descrizione completa dei token, vedere [gestire i token dell'account](https://platform.acedata.cloud/documents/platform-token). Questa interfaccia utilizza Account Token e non utilizza Credential aziendali.

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

## Panoramica dell'interfaccia

| Voce | Contenuto |
| - | - |
| Metodo | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Autenticazione | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`（`platform:read` / `platform` possono includere espandendosi） |
| Ambito dei permessi | Per gli utenti normali è fisso sul proprio utilizzo a pagamento; gli amministratori possono passare `user_id` |

## Parametri di query

| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
| - | - | - | - | - |
| `created_at_from` | date / datetime | No | Il primo giorno del mese corrente nel fuso orario selezionato | Ora di inizio, nome del parametro consigliato |
| `created_at_to` | date / datetime | No | Ora corrente | Ora di fine, nome del parametro consigliato |
| `timezone` | string | No | `UTC` | Fuso orario IANA, ad esempio `Asia/Shanghai`; i valori non validi tornano a UTC |
| `service_id` | UUID | No | — | Filtra per servizio; supporta parametri ripetuti |
| `application_id` | UUID | No | — | Filtra per Application; supporta parametri ripetuti |
| `api_id` | UUID | No | — | Filtra per API; supporta parametri ripetuti |
| `credential_id` | UUID | No | — | Filtra per credenziali API; supporta parametri ripetuti |
| `include_models` | boolean | No | `false` | Se calcolare ulteriormente il riepilogo della dimensione del modello; aumenta il costo della query |
| `user_id` | UUID | No | Per gli utenti normali è fisso sul proprio account; per gli amministratori, se omesso, include tutti gli account | Solo gli amministratori possono specificare qualsiasi account |

`start_time` / `end_time` possono ancora essere utilizzati come alias di compatibilità per i client precedenti; per le nuove integrazioni utilizzare uniformemente `created_at_from` / `created_at_to`. La forma data di `created_at_to` includerà quel giorno naturale, utilizzando cioè la mezzanotte del giorno successivo come confine.

## Esempi di richiesta

Interroga il riepilogo giornaliero/API del mese corrente nel fuso orario di Pechino, includendo la dimensione del modello:

```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}"
```

Interroga l'utilizzo di una settimana per l'Application specificata:

```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}"
```

Esempio 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"])
```

## Esempio di risposta

```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
    }
  ]
}
```

## Campi della risposta

| Campo | Descrizione |
| - | - |
| `items` | Raggruppati per data nel fuso orario selezionato e `api_id`; ogni riga contiene `date`, `api_id`, `amount` |
| `total` | Somma di `deducted_amount` nell'ambito della query |
| `apis` | Mappatura dall'ID API al riepilogo del titolo, per facilitare la visualizzazione di `items` |
| `requests` | Numero totale di richieste nell'ambito della query |
| `models` | Calcolato solo quando `include_models=true`; ogni voce contiene `model`, `amount`, `requests` |

L'unità di quota dipende da `service.unit` dell'Application correlata. Se la query include servizi con unità diverse, eseguire prima statistiche separate per `service_id` o `application_id`, evitando confronti o somme dirette.

Quando l'ora di fine non è successiva all'ora di inizio, l'interfaccia restituisce una struttura vuota completa: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Errori e suggerimenti sulle prestazioni

| HTTP | `error` | Modalità di gestione |
| - | - | - |
| 400 | `usage_history_expired` | Regolare l'intervallo di tempo a dopo `available_from` nella risposta |
| 401 | `not_authenticated` | Controllare l'Account Token, non utilizzare per errore Credential aziendali |
| 403 | `permission_denied` | Gli utenti normali non possono interrogare altri account |

* Per impostazione predefinita non abilitare `include_models`; abilitarlo solo quando il report richiede effettivamente una suddivisione per modello.
* Per query su intervalli ampi, separare preferibilmente per `service_id` o `application_id`, evitando sia unità miste sia costi di query più elevati.
* Le date senza chiamate non vengono automaticamente completate con zero; il client deve completare l'asse delle date prima del rendering del grafico.

## Passaggi successivi

* [Visualizza i record delle chiamate](https://platform.acedata.cloud/documents/platform-usage-list)：individua i dettagli che costituiscono il risultato aggregato.
* [Esporta il volume delle chiamate](https://platform.acedata.cloud/documents/platform-usage-export)：scarica il dettaglio completo in CSV.
* [Visualizza i dettagli della richiesta del servizio](https://platform.acedata.cloud/documents/platform-application-detail)：conferma il saldo e l'unità.


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