> ## 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 estadísticas agregadas de uso de API de la plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Resume por fecha y API el número de solicitudes y la cuota realmente deducida de la cuenta actual, adecuado para crear informes mensuales, gráficos de tendencias y análisis de costos. Para depurar registro por registro, use la [lista de registros de llamadas](https://platform.acedata.cloud/documents/platform-usage-list); para obtener detalles completos sin conexión, use la [exportación de volumen de llamadas](https://platform.acedata.cloud/documents/platform-usage-export).

## Preparativos

1. Inicie sesión en la [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Cree un token de cuenta en la [consola de Account Token](https://platform.acedata.cloud/console/platform-tokens) y guárdelo inmediatamente.
3. Si necesita reducir el alcance, obtenga los ID correspondientes desde la [lista de solicitudes de servicio](https://platform.acedata.cloud/documents/platform-application-list), la [lista de credenciales de API](https://platform.acedata.cloud/documents/platform-credential-list) o la [lista de API](https://platform.acedata.cloud/documents/platform-api-list).

Consulte la explicación completa de los tokens en [administrar tokens de cuenta](https://platform.acedata.cloud/documents/platform-token). Esta interfaz usa Account Token, no Credential de negocio.

```shell theme={null}
export PLATFORM_TOKEN='tu token de cuenta'
```

## Resumen de la interfaz

| Elemento | Contenido |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Autenticación | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` pueden incluirlo) |
| Alcance de permisos | Para usuarios normales se limita a su propio uso facturado; los administradores pueden pasar `user_id` |

## Parámetros de consulta

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
| - | - | - | - | - |
| `created_at_from` | date / datetime | No | El primer día del mes actual en la zona horaria seleccionada | Hora de inicio, nombre de parámetro recomendado |
| `created_at_to` | date / datetime | No | Hora actual | Hora de finalización, nombre de parámetro recomendado |
| `timezone` | string | No | `UTC` | Zona horaria IANA, por ejemplo `Asia/Shanghai`; los valores no válidos vuelven a UTC |
| `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 |
| `include_models` | boolean | No | `false` | Si se calculan adicionalmente los resúmenes por dimensión de modelo; aumentará el costo de consulta |
| `user_id` | UUID | No | Para usuarios normales se fija en sí mismos; si los administradores no lo pasan, incluye todas las cuentas | Solo los administradores pueden especificar cualquier cuenta |

`start_time` / `end_time` aún pueden usarse como alias de compatibilidad para clientes antiguos; las nuevas integraciones usan de forma unificada `created_at_from` / `created_at_to`. La forma de fecha de `created_at_to` incluirá ese día natural, es decir, se usa como límite la medianoche del día siguiente.

## Ejemplos de solicitudes

Consultar el resumen diario/API del mes actual en hora de Beijing, con dimensión de modelo incluida:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Consultar el uso de una semana de la Application especificada:

```shell theme={null}
export APPLICATION_ID='tu ID de Application'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Ejemplo de Python:

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## Ejemplo de respuesta

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## Campos de respuesta

| Campo | Descripción |
| - | - |
| `items` | Agrupado por la fecha de la zona horaria seleccionada y `api_id`; cada fila contiene `date`, `api_id`, `amount` |
| `total` | La suma de `deducted_amount` dentro del rango de consulta |
| `apis` | Mapeo del ID de API al resumen de título, para facilitar la visualización de `items` |
| `requests` | El número total de solicitudes dentro del rango de consulta |
| `models` | Solo se calcula cuando `include_models=true`; cada elemento contiene `model`, `amount`, `requests` |

La unidad de cuota depende de `service.unit` de la Application correspondiente. Si la consulta incluye servicios con diferentes unidades, primero realice las estadísticas por separado según `service_id` o `application_id`, para evitar compararlos o sumarlos directamente.

Cuando la hora de finalización no es mayor que la hora de inicio, la interfaz devuelve una estructura vacía completa: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Errores y recomendaciones de rendimiento

| HTTP | `error` | Método de manejo |
| - | - | - |
| 400 | `usage_history_expired` | Ajuste el rango de tiempo para que sea posterior a `available_from` de la respuesta |
| 401 | `not_authenticated` | Compruebe el Account Token, no use por error el Credential de negocio |
| 403 | `permission_denied` | Los usuarios normales no pueden consultar otras cuentas |

* No habilite `include_models` de forma predeterminada; actívelo solo cuando el informe realmente requiera un desglose por modelo.
* Para consultas de gran alcance, priorice separarlas por `service_id` o `application_id`, lo que evita mezclar unidades y también reduce el costo de consulta.
* Las fechas sin llamadas no se rellenan automáticamente con cero; el cliente debe completar el eje de fechas antes de crear gráficos.

## Siguiente paso

* [Ver registros de llamadas](https://platform.acedata.cloud/documents/platform-usage-list): localizar los detalles que componen los resultados agregados.
* [Exportar volumen de llamadas](https://platform.acedata.cloud/documents/platform-usage-export): descargar los detalles completos en CSV.
* [Ver detalles de la solicitud del servicio](https://platform.acedata.cloud/documents/platform-application-detail): confirmar el saldo y las unidades.


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