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

# Obtener registros de llamadas Proxy de la plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Consulta los registros de uso de la cuenta actual bajo servicios de tipo Proxy. Para llamadas API normales, utiliza [Registros de llamadas API](https://platform.acedata.cloud/documents/platform-usage-list). Si no estás seguro del tipo de servicio, primero puedes consultar el `type` en los [detalles del servicio](https://platform.acedata.cloud/documents/platform-service-detail).

## Preparativos

1. Inicia sesión en la [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Crea un token de cuenta en la [consola de Account Token](https://platform.acedata.cloud/console/platform-tokens) y guárdalo inmediatamente en un gestor de contraseñas o Secret Manager.
3. Abre la [página de perfil](https://auth.acedata.cloud/user/profile) para copiar el UUID de la cuenta actual y guárdalo como `USER_ID`. También se puede usar el `user_id` de la respuesta de creación del token de cuenta.
4. Obtén el `application_id` de un servicio de tipo Proxy desde la [lista de solicitudes de servicio](https://platform.acedata.cloud/documents/platform-application-list). Cuando necesites filtrar por punto de conexión Proxy, obtén el `proxy_id` desde la [lista de Proxy bajo el servicio](https://platform.acedata.cloud/documents/platform-service-proxies).

Para la explicación completa de los tokens, consulta [Administrar tokens de cuenta](https://platform.acedata.cloud/documents/platform-token). Esta interfaz utiliza Account Token, no el Credential para llamar a API de negocio.

```shell theme={null}
export PLATFORM_TOKEN='tu token de cuenta'
export USER_ID='tu UUID de cuenta'
export APPLICATION_ID='tu Proxy Application ID'
```

## Resumen de la interfaz

| Elemento | Contenido |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/proxies/` |
| Autenticación | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| Scope | `usage:read` |
| Paginación | `count` + `items`, 10 registros por página de forma predeterminada |

Cuando el propietario de la Application consulta por `application_id`, el servidor primero sincroniza los registros disponibles de esa Application y luego devuelve la lista, por lo que el tiempo de respuesta puede ser más largo que el de una lista de uso de API normal. Los usuarios autorizados pueden leer los registros visibles existentes, pero no activarán la sincronización del lado del propietario.

## Parámetros de consulta

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| - | - | - | - | - |
| `user_id` | UUID | Obligatorio para usuarios normales | — | UUID de la cuenta actual; pasar otra cuenta devolverá `403` |
| `application_id` | UUID | Recomendado | — | Filtra por Proxy Application; admite parámetros repetidos |
| `proxy_id` | UUID | No | — | Filtra por punto de conexión Proxy; admite parámetros repetidos |
| `limit` | integer | No | 10 | Registros por página, máximo 100 |
| `offset` | integer | No | 0 | Desplazamiento de paginación |
| `ordering` | string | No | `-created_at` | Orden descendente por hora de creación |

La interfaz actual no admite filtrar directamente por modelo, código de estado HTTP, Credential o intervalo de tiempo, y tampoco admite el parámetro `perspective` de la interfaz de uso de API. No añadas estos parámetros no compatibles a la solicitud y asumas que han surtido efecto.

## Ejemplo de solicitud

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

Ejemplo de paginación en 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"])
```

## Ejemplo de respuesta

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

## Campos clave

| Campo | Descripción |
| - | - |
| `user_id` | Cuenta que asume este cargo |
| `actor_user_id` | Llamador real; los registros antiguos pueden estar vacíos |
| `application_id` | Proxy Application que generó este registro |
| `proxy_id` | Punto de conexión Proxy correspondiente |
| `credential_id` | ID de credencial asociada; los registros antiguos pueden estar vacíos |
| `used_amount` | Uso del registro original; puede estar vacío |
| `deducted_amount` | Importe final realmente deducido |
| `remaining_amount` | Saldo restante de la Application después del cargo |
| `metadata` | Metadatos públicos; pueden estar vacíos |
| `service` / `credential` | Resumen de objetos asociados para facilitar la visualización; puede estar vacío si el objeto asociado no existe |

La unidad de cuota está determinada por `service.unit` de la Application correspondiente.

## Gestión de errores

| HTTP | Significado | Método de gestión |
| - | - | - |
| 401 | Token de cuenta faltante o no válido | Comprueba el Account Token, no uses por error el Credential de negocio |
| 403 | Sin autorización para ver los registros solicitados | Utiliza la Application de la cuenta actual, elimina el `user_id` no autorizado |
| 5xx | Fallo temporal de sincronización o consulta | Conserva las condiciones de filtrado y vuelve a intentarlo con retroceso; si el fallo persiste, proporciona el Application ID y la hora al personal de soporte |

## Siguientes pasos

* [Ver registros de llamadas API](https://platform.acedata.cloud/documents/platform-usage-list): consulta los detalles de servicios de tipo API normal.
* [Obtener la lista de Proxy bajo el servicio](https://platform.acedata.cloud/documents/platform-service-proxies): obtén el `proxy_id`.
* [Ver detalles de la solicitud de servicio](https://platform.acedata.cloud/documents/platform-application-detail): confirma la cuota restante y la unidad.


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