> ## 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 registros de chamadas de API da plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Consulte os detalhes das chamadas de API de negócios da conta atual nos últimos 60 dias, adequado para verificar cobranças, localizar solicitações com falha e investigar problemas por serviço, Application, API ou credencial.

> Esta página consulta os registros de chamadas da própria conta. Se desejar apenas visualizar as estatísticas públicas de chamadas de uma API em toda a plataforma, use [Estatísticas de chamadas de API](https://platform.acedata.cloud/documents/platform-api-usage).

## Preparativos

### 1. Criar um token de conta

Esta interface pertence à API de gerenciamento da plataforma e requer o uso de um **Account Token (token de conta)**:

1. Faça login na [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Abra o [console do Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. Clique em «Criar» e salve imediatamente o token em um gerenciador de senhas ou Secret Manager.

Consulte as instruções completas em [Gerenciar tokens de conta da plataforma AceDataCloud](https://platform.acedata.cloud/documents/platform-token). O token de conta é usado para `platform.acedata.cloud/api/v1/**`; para chamar as interfaces de negócios `api.acedata.cloud/**`, são usadas credenciais de API (Credential), e os dois não podem ser misturados.

```shell theme={null}
export PLATFORM_TOKEN='seu token de conta'
```

Não escreva o token em código de frontend, logs ou repositórios públicos; se ele vazar, exclua-o e recrie-o imediatamente no console.

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

É possível visualizar os registros aos quais a conta atual tem permissão de acesso sem fornecer condições de filtro. Quando precisar restringir o escopo:

* `application_id`: obtenha na [lista de solicitações de serviço](https://platform.acedata.cloud/documents/platform-application-list);
* `credential_id`: obtenha na [lista de credenciais de API](https://platform.acedata.cloud/documents/platform-credential-list);
* `api_id`: obtenha na [lista de APIs](https://platform.acedata.cloud/documents/platform-api-list);
* `service_id`: obtenha na [lista de serviços](https://platform.acedata.cloud/documents/platform-service-list).

Usuários comuns não precisam fornecer `user_id`; se fornecido explicitamente, ele deve corresponder à conta atual, caso contrário será retornado `403`. Administradores podem usar este parâmetro para filtrar entre contas.

## Visão geral da interface

| Item | Conteúdo |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| Autenticação | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` podem incluir por expansão) |
| Paginação | `count` + `items`, 10 itens por página por padrão |

## Escopo da consulta

| `perspective` | Significado |
| - | - |
| `both` | Valor padrão; retorna registros pagos ou efetivamente chamados pela conta atual |
| `billing` | Retorna apenas registros pagos pela conta atual |
| `actor` | Retorna apenas registros efetivamente chamados pela conta atual |

## Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `perspective` | string | Não | `both` | `billing`, `actor` ou `both` |
| `user_id` | UUID | Não | — | Somente administradores filtram por usuário; suporta parâmetros repetidos |
| `service_id` | UUID | Não | — | Filtra por serviço; suporta parâmetros repetidos |
| `application_id` | UUID | Não | — | Filtra por Application; suporta parâmetros repetidos |
| `api_id` | UUID | Não | — | Filtra por API; suporta parâmetros repetidos |
| `credential_id` | UUID | Não | — | Filtra por credencial de API; suporta parâmetros repetidos |
| `status_code` | integer | Não | — | Filtra por código de status HTTP; suporta valores repetidos ou separados por vírgulas |
| `created_at_from` | datetime | Não | — | Limite inferior do horário de criação, ISO 8601 |
| `created_at_to` | datetime | Não | — | Limite superior do horário de criação, ISO 8601 |
| `limit` | integer | Não | 10 | Número de itens por página, máximo de 100 |
| `offset` | integer | Não | 0 | Deslocamento da paginação |
| `ordering` | string | Não | `-created_at` | Ordem decrescente por horário de criação |

Quando o horário da solicitação for anterior aos últimos 60 dias, a interface retornará um erro de validação de campo `400`, indicando que os detalhes completos das chamadas são mantidos apenas por 60 dias.

## Exemplos de solicitação

Consultar os 100 registros mais recentes:

```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 horário, Application e status de falha:

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

Exemplo de paginação em 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"])
```

## Exemplo de resposta

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

| Campo | Descrição |
| - | - |
| `user_id` | A conta responsável por esta cobrança |
| `actor_user_id` | A conta que efetivamente iniciou a chamada; pode ser diferente de `user_id` ao autorizar outras pessoas a usar a credencial |
| `used_amount` | O uso desta chamada calculado conforme as regras originais |
| `original_amount` | O uso original antes do desconto da aplicação |
| `deducted_amount` | A cota final efetivamente deduzida |
| `remaining_amount` | A cota restante da Application após a conclusão desta cobrança |
| `elapsed` | O tempo de chamada registrado pelo servidor, em segundos |
| `trace_id` | O identificador de rastreamento usado ao investigar uma única solicitação |
| `metadata` | Metadados públicos; a lista não retorna o conteúdo completo da solicitação ou resposta |
| `api` / `service` / `credential` | Resumos de objetos associados para facilitar a exibição; podem estar vazios quando o objeto associado não existir mais |

A unidade de cota é determinada por `service.unit` da Application correspondente e não deve ser presumida como dólares americanos.

## Erros e novas tentativas

| HTTP | `error` | Significado | Como lidar |
| - | - | - | - |
| 400 | Erro de validação de campo | O intervalo de consulta é anterior ao período de retenção de 60 dias | Ajuste o horário de início para os últimos 60 dias |
| 401 | `not_authenticated` | Token da conta ausente ou inválido | Verifique o Account Token; não use incorretamente a Credential de negócio |
| 403 | `permission_denied` | A solicitação inclui registros sem permissão de visualização | Remova as condições de filtragem de usuários não autorizadas |
| 429 | `usage_query_in_progress` | Uma consulta exatamente idêntica ainda está em execução | Aguarde `Retry-After` antes de tentar novamente com recuo |
| 503 | `usage_query_timeout` | A consulta excedeu o limite de segurança do servidor | Reduza o intervalo de tempo ou adicione condições de filtragem antes de tentar novamente |

Mantenha no máximo uma solicitação em andamento para o mesmo conjunto de parâmetros de consulta. Para consultas de grande intervalo, priorize janelas de um dia ou menores; não sobreponha solicitações idênticas em intervalos fixos.

## Próximas etapas

* [Agregar volume de chamadas](https://platform.acedata.cloud/documents/platform-usage-aggregate): veja o uso resumido por data e API.
* [Exportar volume de chamadas](https://platform.acedata.cloud/documents/platform-usage-export): baixe diretamente grandes volumes de detalhes como CSV.
* [Ver registros de chamadas Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage): consulte registros de serviços do tipo Proxy.
* [Ver detalhes da solicitação de serviço](https://platform.acedata.cloud/documents/platform-application-detail): verifique o saldo e a unidade de cota.
* [Rotacionar credenciais de API](https://platform.acedata.cloud/documents/platform-credential-rotate): substitua-as imediatamente quando houver suspeita de vazamento da credencial.


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