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

# Obter estatísticas agregadas de volume de chamadas de API da plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Resume o número de solicitações e os créditos efetivamente deduzidos da conta atual por data e API, adequado para criar relatórios mensais, gráficos de tendências e análises de custo. Use a [lista de registros de chamadas](https://platform.acedata.cloud/documents/platform-usage-list) quando precisar depurar item por item, e use a [exportação de volume de chamadas](https://platform.acedata.cloud/documents/platform-usage-export) quando precisar de detalhes completos offline.

## Preparação

1. Faça login na [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Crie um token de conta no [console Account Token](https://platform.acedata.cloud/console/platform-tokens) e salve-o imediatamente.
3. Se precisar restringir o escopo, obtenha o ID correspondente na [lista de solicitações de serviço](https://platform.acedata.cloud/documents/platform-application-list), na [lista de credenciais de API](https://platform.acedata.cloud/documents/platform-credential-list) ou na [lista de APIs](https://platform.acedata.cloud/documents/platform-api-list).

Consulte a explicação completa sobre tokens em [gerenciar tokens de conta](https://platform.acedata.cloud/documents/platform-token). Esta interface usa Account Token, não usa Credential de negócio.

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

## Visão geral da interface

| Item | Conteúdo |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Autenticação | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| Escopo OAuth | `usage:read`（`platform:read` / `platform` pode incluir de forma expansiva） |
| Escopo de permissão | Usuários comuns são fixados ao seu próprio volume pago; administradores podem passar `user_id` |

## Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `created_at_from` | date / datetime | Não | Primeiro dia do mês atual no fuso horário selecionado | Hora de início, nome de parâmetro recomendado |
| `created_at_to` | date / datetime | Não | Hora atual | Hora de término, nome de parâmetro recomendado |
| `timezone` | string | Não | `UTC` | Fuso horário IANA, por exemplo `Asia/Shanghai`; valores inválidos retornam a UTC |
| `service_id` | UUID | Não | — | Filtrar por serviço; suporta parâmetros repetidos |
| `application_id` | UUID | Não | — | Filtrar por Application; suporta parâmetros repetidos |
| `api_id` | UUID | Não | — | Filtrar por API; suporta parâmetros repetidos |
| `credential_id` | UUID | Não | — | Filtrar por credencial de API; suporta parâmetros repetidos |
| `include_models` | boolean | Não | `false` | Se deve calcular adicionalmente o resumo por dimensão de modelo; aumenta o custo da consulta |
| `user_id` | UUID | Não | Usuários comuns são fixados a si mesmos; administradores sem envio incluem todas as contas | Somente administradores podem especificar qualquer conta |

`start_time` / `end_time` ainda podem ser usados como aliases de compatibilidade para clientes antigos; novas integrações usam uniformemente `created_at_from` / `created_at_to`. O formato de data de `created_at_to` incluirá esse dia natural, ou seja, usa meia-noite do dia seguinte como limite.

## Exemplos de solicitação

Consultar o resumo diário/API deste mês no horário de Pequim e incluir a dimensão de modelo:

```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 o volume de uso de uma semana para uma Application especificada:

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

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

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

## Exemplo de resposta

```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 resposta

| Campo | Descrição |
| - | - |
| `items` | Agrupado por data no fuso horário selecionado e `api_id`; cada linha contém `date`, `api_id`, `amount` |
| `total` | Soma de `deducted_amount` dentro do escopo da consulta |
| `apis` | Mapeamento de ID de API para resumo de título, facilitando a exibição de `items` |
| `requests` | Número total de solicitações dentro do escopo da consulta |
| `models` | Calculado somente quando `include_models=true`; cada item contém `model`, `amount`, `requests` |

A unidade de crédito depende de `service.unit` da Application relacionada. Se a consulta incluir serviços com unidades diferentes, primeiro realize as estatísticas separadamente por `service_id` ou `application_id`, evitando comparação direta ou soma.

Quando o horário de término não for maior que o horário de início, a interface retornará uma estrutura vazia completa: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Erros e recomendações de desempenho

| HTTP | `error` | Método de tratamento |
| - | - | - |
| 400 | `usage_history_expired` | Ajuste o intervalo de tempo para depois de `available_from` na resposta |
| 401 | `not_authenticated` | Verifique o Account Token, não use incorretamente o Credential de negócio |
| 403 | `permission_denied` | Usuários comuns não podem consultar outras contas |

* Por padrão, não habilite `include_models`; habilite-o somente quando o relatório realmente precisar de divisão por modelos.
* Para consultas de grande alcance, priorize a separação por `service_id` ou `application_id`, evitando tanto a mistura de unidades quanto reduzindo o custo da consulta.
* Datas sem chamadas não receberão zero automaticamente; complete o eixo de datas no cliente antes de criar gráficos.

## Próximos passos

* [Ver registros de chamadas](https://platform.acedata.cloud/documents/platform-usage-list): localizar os detalhes que compõem o resultado agregado.
* [Exportar volume de chamadas](https://platform.acedata.cloud/documents/platform-usage-export): baixar os detalhes completos em CSV.
* [Ver detalhes da solicitação de serviço](https://platform.acedata.cloud/documents/platform-application-detail): confirmar o saldo e a unidade.


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