> ## 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 a la API de la plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Consulta los detalles de las llamadas a la API de negocio de la cuenta actual durante los últimos 60 días; es adecuado para verificar cargos, localizar solicitudes fallidas y solucionar problemas por servicio, Application, API o credencial.

> Esta página consulta los registros de llamadas de la propia cuenta. Si solo desea ver las estadísticas públicas de llamadas de una API en toda la plataforma, utilice las [estadísticas de llamadas a la API](https://platform.acedata.cloud/documents/platform-api-usage).

## Preparación

### 1. Crear un token de cuenta

Esta interfaz pertenece a la API de administración de la plataforma y requiere el uso de un **Account Token (token de cuenta)**:

1. Inicie sesión en la [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Abra la [consola de Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. Haga clic en «Crear» y guarde inmediatamente el token en un administrador de contraseñas o Secret Manager.

Consulte las instrucciones completas en [Administrar los tokens de cuenta de la plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token). El token de cuenta se utiliza para `platform.acedata.cloud/api/v1/**`; las interfaces de negocio `api.acedata.cloud/**` utilizan credenciales de API (Credential), y ambas no pueden mezclarse.

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

No escriba el token en código frontend, registros o repositorios públicos; si se filtra, elimínelo y vuelva a crearlo inmediatamente en la consola.

### 2. Preparar ID de filtro (opcional)

Puede ver los registros que la cuenta actual tiene permiso para consultar sin pasar condiciones de filtro. Cuando necesite reducir el alcance:

* `application_id`: obténgalo de la [lista de solicitudes de servicio](https://platform.acedata.cloud/documents/platform-application-list);
* `credential_id`: obténgalo de la [lista de credenciales de API](https://platform.acedata.cloud/documents/platform-credential-list);
* `api_id`: obténgalo de la [lista de API](https://platform.acedata.cloud/documents/platform-api-list);
* `service_id`: obténgalo de la [lista de servicios](https://platform.acedata.cloud/documents/platform-service-list).

Los usuarios normales no necesitan pasar `user_id`; si se pasa explícitamente, debe coincidir con la cuenta actual; de lo contrario, se devuelve `403`. Los administradores pueden usar este parámetro para filtrar entre cuentas.

## Resumen de la interfaz

| Elemento | Contenido |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| Autenticación | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` se pueden expandir para incluirlo) |
| Paginación | `count` + `items`, 10 elementos por página de forma predeterminada |

## Alcance de la consulta

| `perspective` | Significado |
| - | - |
| `both` | Valor predeterminado; devuelve registros pagados o realmente llamados por la cuenta actual |
| `billing` | Devuelve solo registros pagados por la cuenta actual |
| `actor` | Devuelve solo registros realmente llamados por la cuenta actual |

## Parámetros de consulta

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| - | - | - | - | - |
| `perspective` | string | No | `both` | `billing`, `actor` o `both` |
| `user_id` | UUID | No | — | Solo los administradores filtran por usuario; admite parámetros repetidos |
| `service_id` | UUID | No | — | Filtrar por servicio; admite parámetros repetidos |
| `application_id` | UUID | No | — | Filtrar por Application; admite parámetros repetidos |
| `api_id` | UUID | No | — | Filtrar por API; admite parámetros repetidos |
| `credential_id` | UUID | No | — | Filtrar por credencial de API; admite parámetros repetidos |
| `status_code` | integer | No | — | Filtrar por código de estado HTTP; admite valores repetidos o separados por comas |
| `created_at_from` | datetime | No | — | Límite inferior de tiempo de creación, ISO 8601 |
| `created_at_to` | datetime | No | — | Límite superior de tiempo de creación, ISO 8601 |
| `limit` | integer | No | 10 | Número de elementos por página, máximo 100 |
| `offset` | integer | No | 0 | Desplazamiento de paginación |
| `ordering` | string | No | `-created_at` | Orden descendente por tiempo de creación |

Cuando el tiempo de solicitud sea anterior a los últimos 60 días, la interfaz devuelve un error de validación de campo `400`, indicando que los detalles completos de las llamadas solo se conservan durante 60 días.

## Ejemplos de solicitud

Consultar los 100 registros más recientes:

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

Filtrar por tiempo, Application y estado de error:

```shell theme={null}
export APPLICATION_ID='你的 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}"
```

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

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

## Campos clave

| Campo | Descripción |
| - | - |
| `user_id` | La cuenta que asume este cargo |
| `actor_user_id` | La cuenta que realmente inicia la llamada; puede diferir de `user_id` al autorizar a otros a usar credenciales |
| `used_amount` | El uso de esta llamada calculado según las reglas originales |
| `original_amount` | El uso original antes de aplicar descuentos de la aplicación |
| `deducted_amount` | La cuota finalmente deducida |
| `remaining_amount` | La cuota restante de la Application tras completar este cargo |
| `elapsed` | El tiempo de llamada registrado por el servidor, en segundos |
| `trace_id` | El identificador de seguimiento utilizado al investigar una sola solicitud |
| `metadata` | Metadatos públicos; la lista no devolverá el contenido completo de la solicitud o respuesta |
| `api` / `service` / `credential` | Resúmenes de objetos relacionados para facilitar la visualización; pueden estar vacíos si el objeto relacionado ya no existe |

La unidad de cuota la determina `service.unit` de la Application correspondiente, y no debe asumirse por defecto como dólares estadounidenses.

## Errores y reintentos

| HTTP | `error` | Significado | Método de manejo |
| - | - | - | - |
| 400 | Error de validación de campos | El rango de consulta es anterior al período de retención de 60 días | Ajuste la hora de inicio para que esté dentro de los últimos 60 días |
| 401 | `not_authenticated` | El token de cuenta falta o no es válido | Verifique el Account Token, no use por error la Credential de negocio |
| 403 | `permission_denied` | La solicitud contiene registros que no tiene permiso para ver | Elimine las condiciones de filtrado de usuarios no autorizados |
| 429 | `usage_query_in_progress` | Una consulta exactamente igual sigue en ejecución | Espere `Retry-After` antes de realizar un reintento con retroceso |
| 503 | `usage_query_timeout` | La consulta supera el límite de tiempo seguro del servidor | Reduzca el rango de tiempo o añada condiciones de filtrado antes de reintentar |

Como máximo, mantenga una solicitud en curso para el mismo conjunto de parámetros de consulta. Para consultas de gran alcance, priorice ventanas de un día o menores, y no superponga solicitudes idénticas a intervalos fijos.

## Próximos pasos

* [Agregar el volumen de llamadas](https://platform.acedata.cloud/documents/platform-usage-aggregate): consulte el uso resumido por fecha y API.
* [Exportar el volumen de llamadas](https://platform.acedata.cloud/documents/platform-usage-export): descargue grandes cantidades de detalles directamente como CSV.
* [Ver registros de llamadas Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage): consulte registros de servicios de tipo Proxy.
* [Ver detalles de la solicitud de servicio](https://platform.acedata.cloud/documents/platform-application-detail): verifique el saldo y la unidad de cuota.
* [Rotar credenciales de API](https://platform.acedata.cloud/documents/platform-credential-rotate): reemplácelas inmediatamente si se sospecha que las credenciales se han filtrado.


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