Ottenere i record delle chiamate API della piattaforma AceDataCloud

Interroga i dettagli delle chiamate API aziendali degli ultimi 60 giorni dell’account corrente, adatto per verificare gli addebiti, individuare le richieste non riuscite e risolvere problemi per servizio, Application, API o credenziale.

Questa pagina interroga i record di chiamata dell’account stesso. Se vuoi visualizzare solo le statistiche pubbliche delle chiamate di una determinata API sull’intera piattaforma, usa le Statistiche delle chiamate API.

Preparazione

1. Creare un token dell’account

Questa interfaccia appartiene alle API di gestione della piattaforma e richiede l’uso di un Account Token (token dell’account):

Accedi alla piattaforma AceDataCloud.
Apri la console Account Token.
Fai clic su «Crea» e salva immediatamente il token in un gestore di password o in Secret Manager.

Per le istruzioni complete, consulta Gestire i token dell’account della piattaforma AceDataCloud. Il token dell’account è usato per platform.acedata.cloud/api/v1/**; per chiamare le interfacce aziendali api.acedata.cloud/** vengono usate le credenziali API (Credential), e i due non possono essere utilizzati in modo intercambiabile.

export PLATFORM_TOKEN='il tuo token dell'account'

Non scrivere il token nel codice frontend, nei log o nei repository pubblici; se viene divulgato, eliminalo e ricrealo immediatamente nella console.

2. Preparare gli ID di filtro (facoltativo)

Senza passare condizioni di filtro, puoi visualizzare i record che l’account corrente è autorizzato a visualizzare. Quando è necessario restringere l’ambito:

application_id: ottienilo dall’elenco delle richieste di servizio;
credential_id: ottienilo dall’elenco delle credenziali API;
api_id: ottienilo dall’elenco delle API;
service_id: ottienilo dall’elenco dei servizi.

Gli utenti normali non devono passare user_id; se viene passato esplicitamente, deve corrispondere all’account corrente, altrimenti viene restituito 403. Gli amministratori possono usare questo parametro per filtrare tra account diversi.

Panoramica dell’interfaccia

Voce	Contenuto
Metodo	`GET`
URL	`https://platform.acedata.cloud/api/v1/usage/apis/`
Autenticazione	`Authorization: Bearer ${PLATFORM_TOKEN}`
OAuth Scope	`usage:read` (`platform:read` / `platform` può includerlo)
Paginazione	`count` + `items`, 10 elementi per pagina per impostazione predefinita

Ambito della query

`perspective`	Significato
`both`	Valore predefinito; restituisce i record pagati o effettivamente chiamati dall’account corrente
`billing`	Restituisce solo i record pagati dall’account corrente
`actor`	Restituisce solo i record effettivamente chiamati dall’account corrente

Parametri della query

Parametro	Tipo	Obbligatorio	Predefinito	Descrizione
`perspective`	string	No	`both`	`billing`, `actor` o `both`
`user_id`	UUID	No	—	Solo gli amministratori filtrano per utente; supporta parametri ripetuti
`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 credenziale API; supporta parametri ripetuti
`status_code`	integer	No	—	Filtra per codice di stato HTTP; supporta valori ripetuti o separati da virgole
`created_at_from`	datetime	No	—	Limite inferiore dell’orario di creazione, ISO 8601
`created_at_to`	datetime	No	—	Limite superiore dell’orario di creazione, ISO 8601
`limit`	integer	No	10	Numero di elementi per pagina, massimo 100
`offset`	integer	No	0	Offset della paginazione
`ordering`	string	No	`-created_at`	Ordine decrescente per orario di creazione

Quando l’orario della richiesta è precedente agli ultimi 60 giorni, l’interfaccia restituisce un errore di convalida del campo 400, indicando che i dettagli completi delle chiamate vengono conservati solo per 60 giorni.

Esempi di richiesta

Interroga gli ultimi 100 record:

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

Filtra per orario, Application e stato di errore:

export APPLICATION_ID='il tuo 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}"

Esempio di paginazione Python:

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

Esempio di risposta

{
  "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"}
    }
  ]
}

Campi chiave

Campo	Descrizione
`user_id`	L’account che sostiene questo addebito
`actor_user_id`	L’account che avvia effettivamente la chiamata; può differire da `user_id` quando si autorizzano altri a utilizzare le credenziali
`used_amount`	Il consumo di questa chiamata calcolato secondo le regole originali
`original_amount`	Il consumo originale prima dell’applicazione dello sconto
`deducted_amount`	La quota effettivamente detratta in via definitiva
`remaining_amount`	La quota residua dell’Application dopo il completamento di questo addebito
`elapsed`	Il tempo di chiamata registrato dal server, in secondi
`trace_id`	L’identificatore di tracciamento utilizzato per analizzare una singola richiesta
`metadata`	Metadati pubblici; l’elenco non restituisce il contenuto completo della richiesta o della risposta
`api` / `service` / `credential`	Riepiloghi degli oggetti associati per una visualizzazione agevole; possono essere vuoti se l’oggetto associato non esiste più

L’unità della quota è determinata da service.unit dell’Application corrispondente e non deve essere considerata per impostazione predefinita come dollari statunitensi.

Errori e tentativi

HTTP	`error`	Significato	Metodo di gestione
400	Errore di convalida del campo	L’intervallo di query è precedente al periodo di conservazione di 60 giorni	Regolare l’ora di inizio entro gli ultimi 60 giorni
401	`not_authenticated`	Token dell’account mancante o non valido	Controllare l’Account Token, non utilizzare erroneamente il Credential aziendale
403	`permission_denied`	La richiesta include record che non si è autorizzati a visualizzare	Rimuovere le condizioni di filtro degli utenti non autorizzati
429	`usage_query_in_progress`	Una query completamente identica è ancora in esecuzione	Attendere `Retry-After` prima di riprovare con backoff
503	`usage_query_timeout`	La query supera il limite di sicurezza del server	Ridurre l’intervallo di tempo o aggiungere condizioni di filtro prima di riprovare

Per lo stesso gruppo di parametri di query, mantenere al massimo una richiesta in corso. Per le query su ampi intervalli, utilizzare preferibilmente finestre di un giorno o più piccole e non sovrapporre richieste identiche a intervalli fissi.

Passaggi successivi

Aggregare il volume delle chiamate: visualizzare il consumo riepilogato per data e API.
Esportare il volume delle chiamate: scaricare direttamente grandi quantità di dettagli in formato CSV.
Visualizzare i record delle chiamate Proxy: interrogare i record dei servizi di tipo Proxy.
Visualizzare i dettagli della richiesta di servizio: verificare il saldo e l’unità della quota.
Ruotare le credenziali API: sostituirle immediatamente in caso di sospetta compromissione delle credenziali.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Ottenere i record delle chiamate API della piattaforma AceDataCloud

Preparazione

1. Creare un token dell’account

2. Preparare gli ID di filtro (facoltativo)

Panoramica dell’interfaccia

Ambito della query

Parametri della query

Esempi di richiesta

Esempio di risposta

Campi chiave

Errori e tentativi

Passaggi successivi

​Preparazione

​1. Creare un token dell’account

​2. Preparare gli ID di filtro (facoltativo)

​Panoramica dell’interfaccia

​Ambito della query

​Parametri della query

​Esempi di richiesta

​Esempio di risposta

​Campi chiave

​Errori e tentativi

​Passaggi successivi

Preparazione

1. Creare un token dell’account

2. Preparare gli ID di filtro (facoltativo)

Panoramica dell’interfaccia

Ambito della query

Parametri della query

Esempi di richiesta

Esempio di risposta

Campi chiave

Errori e tentativi

Passaggi successivi