> ## 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 i record delle chiamate API della piattaforma AceDataCloud

> Platform API guide - Ace Data Cloud

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](https://platform.acedata.cloud/documents/platform-api-usage).

## 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)**:

1. Accedi alla [piattaforma AceDataCloud](https://platform.acedata.cloud).
2. Apri la [console Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. 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](https://platform.acedata.cloud/documents/platform-token). 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.

```shell theme={null}
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](https://platform.acedata.cloud/documents/platform-application-list);
* `credential_id`: ottienilo dall'[elenco delle credenziali API](https://platform.acedata.cloud/documents/platform-credential-list);
* `api_id`: ottienilo dall'[elenco delle API](https://platform.acedata.cloud/documents/platform-api-list);
* `service_id`: ottienilo dall'[elenco dei servizi](https://platform.acedata.cloud/documents/platform-service-list).

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:

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

Filtra per orario, Application e stato di errore:

```shell theme={null}
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:

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

## Esempio di risposta

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

## 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](https://platform.acedata.cloud/documents/platform-usage-aggregate): visualizzare il consumo riepilogato per data e API.
* [Esportare il volume delle chiamate](https://platform.acedata.cloud/documents/platform-usage-export): scaricare direttamente grandi quantità di dettagli in formato CSV.
* [Visualizzare i record delle chiamate Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage): interrogare i record dei servizi di tipo Proxy.
* [Visualizzare i dettagli della richiesta di servizio](https://platform.acedata.cloud/documents/platform-application-detail): verificare il saldo e l'unità della quota.
* [Ruotare le credenziali API](https://platform.acedata.cloud/documents/platform-credential-rotate): sostituirle immediatamente in caso di sospetta compromissione delle credenziali.


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