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

# Filtragem e agregação

> Configure filtros para selecionar eventos específicos e escolha como eles serão agregados dentro do ciclo de cobrança.

> Filtros definem **quais eventos contam**. Agregação define **como os valores são combinados**. Juntos, eles transformam uma massa de eventos brutos em um número preciso para cobrança.

## Filtragem de eventos

Filtros permitem selecionar um subconjunto de eventos com base em suas propriedades. No Dashboard, os filtros são configurados diretamente na tela de edição do recurso:

<Frame>
  <img src="https://mintcdn.com/aira-e93056c6/D0DI4R_7r28AeG1L/static/edit-resource.png?fit=max&auto=format&n=D0DI4R_7r28AeG1L&q=85&s=4734b18de30aa108028878c0e7f8dc5e" alt="Aira — Configuração de filtros de um recurso" width="1606" height="1990" data-path="static/edit-resource.png" />
</Frame>

* **`eventName`** — inclua um ou mais tipos de evento (ex: `api_request`, `storage_used`)
* **Propriedades:** Restrinja por valores dentro de `properties` (ex: `region = "sa-east-1"`)
* **Tags:** Classifique eventos por categorias adicionais

```
Filtro: eventName IN ("ticket_resolved_ai", "ticket_resolved_human")
        AND properties.channel = "chat"

→ Inclui apenas tickets resolvidos via chat, por qualquer tipo de agente
```

<Tip>
  Planeje suas propriedades de evento desde o início da integração. Incluir propriedades como `region`, `plan_tier`, `channel` permite criar recursos com filtros granulares depois, sem alterar o código de envio.
</Tip>

<br />

<h2 id="tipos-de-agregacao">
  Tipos de agregação
</h2>

<Tabs>
  <Tab title="Soma">
    Soma todos os valores dos eventos filtrados ocorridos no período.

    **Quando usar:** métricas cumulativas que partem de zero a cada ciclo — requisições de API, mensagens enviadas, transações processadas.

    ```
    Eventos no período: 120, 80, 300
    Agregação por soma → 120 + 80 + 300 = 500
    ```

    A maioria dos recursos de faturamento baseado em uso utiliza agregação por soma.
  </Tab>

  <Tab title="Último do Período">
    Considera apenas o último valor registrado no período, por tipo de evento.

    **Quando usar:** métricas que representam um estado atual e podem subir ou descer — usuários ativos, tamanho de pool, saldo de licenças.

    ```
    Valores observados: 90 → 110 → 105 → 130
    Último do período → 130
    ```

    <Note>
      Recursos com agregação "Último do Período" podem usar o modelo de cobrança **prorrata diário** em planos, onde o sistema calcula a cobrança proporcional por dia baseado no valor daquele dia.
    </Note>
  </Tab>

  <Tab title="Único">
    Conta o número de valores distintos registrados no período.

    **Quando usar:** métricas que contam entidades únicas — número de clientes ativos, endpoints distintos acessados, dispositivos conectados.

    ```
    Valores: "user_a", "user_b", "user_a", "user_c"
    Únicos → 3 (user_a, user_b, user_c)
    ```
  </Tab>
</Tabs>

<br />

<h2 id="exemplos-praticos">
  Exemplos práticos
</h2>

<h3 id="plataforma-de-api--requisicoes-por-endpoint">
  Plataforma de API — requisições por endpoint
</h3>

**Recurso:** "Requisições ao endpoint /payments"

* Filtro: `eventName = "api_request"` AND `properties.endpoint = "/v1/payments"`
* Agregação: Soma
* Tipo: Unitário
* Resultado: total de chamadas ao endpoint de pagamentos no mês

<h3 id="cloud-storage--armazenamento-diario">
  Cloud storage — armazenamento diário
</h3>

**Recurso:** "Armazenamento utilizado"

* Filtro: `eventName = "storage_snapshot"`
* Agregação: Último do Período
* Tipo: Unitário
* Resultado: quantidade de GB armazenados ao final do mês (não acumulativo)

### Fintech — volume transacionado

**Recurso:** "Volume de transações"

* Filtro: `eventName = "transaction_processed"`
* Agregação: Soma
* Tipo: Monetário (valores em centavos)
* Resultado: total em reais transacionados, usado para cobrar comissão percentual

<br />

<h2 id="proximos-passos">
  Próximos passos
</h2>

* [Tipos de recursos](/recursos/tipos-de-recursos) — entenda a diferença entre unitário e monetário
* [Planos](/planos/criar-planos) — associe recursos a modelos de precificação