> ## 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 Proxy da plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Consulte os registros de uso da conta atual em serviços do tipo Proxy. Para chamadas comuns de API, use os [Registros de chamadas de API](https://platform.acedata.cloud/documents/platform-usage-list). Se não tiver certeza do tipo de serviço, primeiro consulte o `type` nos [detalhes do serviço](https://platform.acedata.cloud/documents/platform-service-detail).

## Preparação

1. Faça login na [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Crie um token de conta no [console de Account Token](https://platform.acedata.cloud/console/platform-tokens) e salve-o imediatamente em um gerenciador de senhas ou Secret Manager.
3. Abra a [página de perfil](https://auth.acedata.cloud/user/profile), copie o UUID da conta atual e salve-o como `USER_ID`. O `user_id` na resposta de criação do token de conta também pode ser usado.
4. Obtenha o `application_id` de um serviço do tipo Proxy na [lista de solicitações de serviço](https://platform.acedata.cloud/documents/platform-application-list). Quando precisar filtrar por endpoint Proxy, obtenha o `proxy_id` na [lista de Proxy do serviço](https://platform.acedata.cloud/documents/platform-service-proxies).

Para a descrição completa dos tokens, consulte [Gerenciar tokens de conta](https://platform.acedata.cloud/documents/platform-token). Esta interface usa Account Token, e não usa a Credential para chamar APIs de negócio.

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

## Visão geral da interface

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

Quando o proprietário da Application consulta por `application_id`, o servidor primeiro sincroniza os registros disponíveis dessa Application e depois retorna a lista; portanto, o tempo de resposta pode ser maior do que o da lista comum de uso de API. Usuários autorizados podem ler os registros visíveis existentes, mas não acionam a sincronização do lado do proprietário.

## Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `user_id` | UUID | Obrigatório para usuários comuns | — | UUID da conta atual; passar outra conta retornará `403` |
| `application_id` | UUID | Recomendado | — | Filtra por Proxy Application; aceita parâmetros repetidos |
| `proxy_id` | UUID | Não | — | Filtra por endpoint Proxy; aceita parâmetros repetidos |
| `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 hora de criação |

A interface atual não suporta filtragem direta por modelo, código de status HTTP, Credential ou intervalo de tempo, nem suporta o parâmetro `perspective` da interface de uso de API. Não adicione esses parâmetros não suportados à solicitação presumindo que eles terão efeito.

## Exemplo de solicitação

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

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

## 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": 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 principais

| Campo | Descrição |
| - | - |
| `user_id` | Conta responsável por esta cobrança |
| `actor_user_id` | Chamador real; registros antigos podem estar vazios |
| `application_id` | Proxy Application que gerou este registro |
| `proxy_id` | Endpoint Proxy correspondente |
| `credential_id` | ID da credencial associada; registros antigos podem estar vazios |
| `used_amount` | Uso do registro original; pode estar vazio |
| `deducted_amount` | Crédito efetivamente deduzido no final |
| `remaining_amount` | Crédito restante da Application após a cobrança |
| `metadata` | Metadados públicos; podem estar vazios |
| `service` / `credential` | Resumo dos objetos associados para exibição; podem estar vazios quando o objeto associado não existe |

A unidade de crédito é determinada por `service.unit` da Application correspondente.

## Tratamento de erros

| HTTP | Significado | Como tratar |
| - | - | - |
| 401 | Token de conta ausente ou inválido | Verifique o Account Token, não use por engano a Credential de negócio |
| 403 | Sem permissão para visualizar os registros solicitados | Use a Application pertencente à conta atual, remova o `user_id` não autorizado |
| 5xx | Falha temporária de sincronização ou consulta | Mantenha as condições de filtro e tente novamente com backoff; em caso de falha persistente, forneça o ID da Application e o horário ao suporte |

## Próximas etapas

* [Ver registros de chamadas de API](https://platform.acedata.cloud/documents/platform-usage-list): consulte os detalhes de serviços comuns do tipo API.
* [Obter lista de Proxy do serviço](https://platform.acedata.cloud/documents/platform-service-proxies): obtenha o `proxy_id`.
* [Ver detalhes da solicitação de serviço](https://platform.acedata.cloud/documents/platform-application-detail): confirme o crédito restante e a unidade.


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