> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Dashboards Configuráveis

> Componha métricas de eventos do sistema e personalizados em dashboards por marca

Dashboards agrupam widgets — contadores, séries temporais, decomposições, funis, tabelas, listas top-n — sobre eventos de agente. Combine canônicos do sistema (`agent_view`, `agent_atc`, `agent_purchase`, ...) com tipos de evento personalizados registrados via o registro de [Tipos de Evento Personalizados](/pt/api-reference/agent-tracking/list-event-types).

## Composição

Um dashboard pertence a uma única marca. Cada widget contém:

* **type** — um dos seis tipos iniciais (`counter`, `time_series`, `breakdown_bar`, `funnel`, `table`, `top_n`)
* **config** — opções específicas do tipo, validadas pelo schema zod do widget. Título e os parâmetros de agregação por widget vivem dentro do `config` (não há colunas `title` ou `aggregation` separadas na linha do widget)
* **position** — coordenadas de grid `(x, y, w, h)` para react-grid-layout

O motor de agregação executa contra `agent_events` no DO Postgres com SQL parametrizado — `workspace_id` e `brand_id` são sempre adicionados ao predicado a partir do contexto da requisição, independente dos filtros enviados pelo usuário, garantindo isolamento por marca por construção. Os resultados são armazenados em cache no Redis por 60 segundos.

## Papéis

* **Members** podem visualizar dashboards
* **Owners** e **admins** podem criar, editar e excluir

## Contexto de marca

Toda leitura e escrita requer contexto de marca. Envie como:

* Header `X-Active-Brand: <uuid>` (preferido), ou
* Query `?brand_id=<uuid>` (alternativa para clientes que não conseguem enviar headers)

Para o endpoint `POST /aggregate`, o header / query é a **única** fonte de contexto de marca — o corpo da requisição não carrega marca. Isso elimina a classe de bugs em que um campo do body discorda do header.

## Veja também

* [API de Dashboards](/pt/api-reference/dashboards/list-dashboards) — operações REST
* [Marcas](/pt/concepts/brands) — a unidade de isolamento que possui cada dashboard