> ## 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 Proxy della piattaforma AceDataCloud

> Platform API guide - Ace Data Cloud

Interroga i record di utilizzo dell'account corrente per i servizi di tipo Proxy. Per le normali chiamate API, utilizza i [record delle chiamate API](https://platform.acedata.cloud/documents/platform-usage-list). Se non sei sicuro del tipo di servizio, puoi prima consultare il `type` nei [dettagli del servizio](https://platform.acedata.cloud/documents/platform-service-detail).

## Preparazione

1. Accedi alla [piattaforma AceDataCloud](https://platform.acedata.cloud).
2. Crea un token dell'account nella [console Account Token](https://platform.acedata.cloud/console/platform-tokens) e salvalo immediatamente in un gestore di password o in Secret Manager.
3. Apri la [pagina del profilo personale](https://auth.acedata.cloud/user/profile), copia l'UUID dell'account corrente e salvalo come `USER_ID`. Può essere utilizzato anche il `user_id` nella risposta di creazione del token dell'account.
4. Ottieni l'`application_id` di un servizio di tipo Proxy dall'[elenco delle richieste di servizio](https://platform.acedata.cloud/documents/platform-application-list). Quando è necessario filtrare per endpoint Proxy, ottieni il `proxy_id` dall'[elenco dei Proxy del servizio](https://platform.acedata.cloud/documents/platform-service-proxies).

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

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
export APPLICATION_ID='你的 Proxy Application ID'
```

## Panoramica dell'interfaccia

| Voce | Contenuto |
| - | - |
| Metodo | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/proxies/` |
| Autenticazione | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| Scope | `usage:read` |
| Paginazione | `count` + `items`, 10 record per pagina per impostazione predefinita |

Quando il proprietario dell'Application esegue una query in base a `application_id`, il server sincronizza prima i record disponibili di tale Application e restituisce poi l'elenco; pertanto, il tempo di risposta potrebbe essere più lungo rispetto al normale elenco di utilizzo API. Gli utenti autorizzati possono leggere i record visibili esistenti, ma non attiveranno la sincronizzazione dal lato del proprietario.

## Parametri di query

| Parametro | Tipo | Obbligatorio | Predefinito | Descrizione |
| - | - | - | - | - |
| `user_id` | UUID | Obbligatorio per gli utenti normali | — | UUID dell'account corrente; il passaggio di un altro account restituisce `403` |
| `application_id` | UUID | Consigliato | — | Filtra per Proxy Application; supporta parametri ripetuti |
| `proxy_id` | UUID | No | — | Filtra per endpoint Proxy; supporta parametri ripetuti |
| `limit` | integer | No | 10 | Numero di record per pagina, massimo 100 |
| `offset` | integer | No | 0 | Offset di paginazione |
| `ordering` | string | No | `-created_at` | Ordine decrescente per data di creazione |

L'interfaccia corrente non supporta il filtro diretto per modello, codice di stato HTTP, Credential o intervallo temporale, né supporta il parametro `perspective` dell'interfaccia di utilizzo API. Non aggiungere alla richiesta questi parametri non supportati presumendo che abbiano effetto.

## Esempio di richiesta

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

Esempio di paginazione Python:

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/proxies/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "user_id": os.environ["USER_ID"],
        "application_id": os.environ["APPLICATION_ID"],
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["deducted_amount"], usage["remaining_amount"])
```

## 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": null,
      "application_id": "00000000-0000-4000-8000-000000000003",
      "proxy_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": null,
      "used_amount": null,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "metadata": null,
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "title": "Example Proxy Service"
      },
      "credential": null
    }
  ]
}
```

## Campi chiave

| Campo | Descrizione |
| - | - |
| `user_id` | Account a cui viene addebitato questo costo |
| `actor_user_id` | Chiamante effettivo; i record meno recenti potrebbero essere vuoti |
| `application_id` | Proxy Application che ha generato questo record |
| `proxy_id` | Endpoint Proxy corrispondente |
| `credential_id` | ID della credenziale associata; i record meno recenti potrebbero essere vuoti |
| `used_amount` | Utilizzo del record originale; potrebbe essere vuoto |
| `deducted_amount` | Quota effettivamente detratta in via definitiva |
| `remaining_amount` | Quota rimanente dell'Application dopo l'addebito |
| `metadata` | Metadati pubblici; potrebbero essere vuoti |
| `service` / `credential` | Riepilogo dell'oggetto associato per una facile visualizzazione; potrebbe essere vuoto se l'oggetto associato non esiste |

L'unità di quota è determinata da `service.unit` dell'Application corrispondente.

## Gestione degli errori

| HTTP | Significato | Modalità di gestione |
| - | - | - |
| 401 | Token dell'account mancante o non valido | Controlla l'Account Token, non utilizzare per errore il Credential aziendale |
| 403 | Non autorizzato a visualizzare i record richiesti | Utilizza l'Application appartenente all'account corrente, rimuovi il `user_id` non autorizzato |
| 5xx | Sincronizzazione o query temporaneamente non riuscita | Conserva le condizioni di filtro e riprova con backoff; in caso di errore persistente, fornisci all'assistenza l'Application ID e l'orario |

## Passaggi successivi

* [Visualizzare i record delle chiamate API](https://platform.acedata.cloud/documents/platform-usage-list): interroga i dettagli dei normali servizi di tipo API.
* [Ottenere l'elenco dei Proxy del servizio](https://platform.acedata.cloud/documents/platform-service-proxies): ottieni `proxy_id`.
* [Visualizzare i dettagli della richiesta di servizio](https://platform.acedata.cloud/documents/platform-application-detail): conferma la quota rimanente e l'unità.


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