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

# Rede e edge

> Gerencie domínios customizados, DNS, analytics da edge, erros, logs de requisição, percentis de latência e invalidação de cache para aplicações website.

<Note>
  Os endpoints desta página se aplicam apenas a **aplicações website** — apps com domínio web. Chamá-los em uma aplicação que não é web falha.
</Note>

```go theme={null}
client := rest.NewClient(os.Getenv("SQUARECLOUD_API_KEY"))
defer client.Close()

api := rest.New(client)
```

## Domínio customizado

`api.SetApplicationCustomDomain(appID, domain)` define o domínio customizado vinculado ao site.

```go theme={null}
err := api.SetApplicationCustomDomain("abc123def456abc123def456", "seusite.com")
if err != nil {
	panic(err)
}
```

## Registros DNS

Depois de vincular um domínio customizado, configure o DNS no seu registrador. `api.GetApplicationDNS(appID)` retorna os registros a criar como um `[]squarecloud.DNSRecord`.

```go theme={null}
records, err := api.GetApplicationDNS("abc123def456abc123def456")
if err != nil {
	panic(err)
}

for _, record := range records {
	fmt.Printf("%s %s → %s (%s)\n", record.Type, record.Name, record.Value, record.Status)
}
```

| Campo    | Tipo     | Descrição                                                                                                                                                       |
| -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Type`   | `string` | `"txt"` ou `"cname"` — os registros TXT cobrem a propriedade do domínio e a validação SSL; o CNAME carrega o tráfego e sempre aponta para `cname.squareweb.app` |
| `Name`   | `string` | Nome do registro a criar                                                                                                                                        |
| `Value`  | `string` | Valor do registro                                                                                                                                               |
| `Status` | `string` | Estado de validação: `"pending"`, `"pending_validation"` ou `"active"`                                                                                          |

## Analytics

`api.GetApplicationAnalytics(appID, start, end)` retorna analytics agregados da edge para a janela informada como um `squarecloud.NetworkAnalytics`. A janela é obrigatória, e a retenção máxima é de **7 dias**.

```go theme={null}
end := time.Now()
start := end.Add(-24 * time.Hour)

analytics, err := api.GetApplicationAnalytics("abc123def456abc123def456", start, end)
if err != nil {
	panic(err)
}

fmt.Println(len(analytics.Visits), "buckets de tempo") // séries de 15 minutos
fmt.Println(analytics.Countries)
fmt.Println(analytics.Paths)
```

A resposta traz séries temporais de 15 minutos (`Visits`, `Countries`, `Devices`, `OS`, `Browsers`, `Protocols`, `Methods`, `Paths`, `Referers`, `Providers`) e buckets de janela inteira (`IPs`, `StatusCodes`, `Bots`, `ContentTypes`).

<Note>
  Para uma janela inteiramente anterior à criação da aplicação, a API retorna um objeto vazio — todos os slices da resposta são `nil`. Verifique os tamanhos antes de indexar.
</Note>

### Filtros de drill-down

Além da janela, o endpoint aceita filtros opcionais como query parameters — passe-os com `rest.WithQueryParam`. Cada filtro restringe todos os breakdowns da resposta de uma vez:

| Filtro         | Notas                                                    |
| -------------- | -------------------------------------------------------- |
| `country`      | Código de país com 2 letras, ex.: `"BR"`                 |
| `ip`           | Correspondência exata de IP                              |
| `path`         | Correspondência por prefixo, ex.: `"/api"`               |
| `status`       | Código de status HTTP, ex.: `"404"`                      |
| `os`           | Sistema operacional                                      |
| `browser`      | Nome do navegador                                        |
| `protocol`     | Protocolo da requisição                                  |
| `referer`      | Use `"Direct"` para requisições sem referer              |
| `provider`     | Provedor de rede, ex.: `"GOOGLE (15169)"` (ASN)          |
| `content_type` | Use `"Unknown"` para tipos de conteúdo não classificados |
| `bot`          | Use `"Unverified"` para tráfego normal (não-bot)         |

```go theme={null}
analytics, err := api.GetApplicationAnalytics(
	"abc123def456abc123def456",
	start, end,
	rest.WithQueryParam("country", "BR"),
	rest.WithQueryParam("status", "404"),
	rest.WithQueryParam("bot", "Unverified"),
)
```

## Monitoramento de erros

`api.GetApplicationNetworkErrors(appID, start, end)` retorna o breakdown de erros da edge. Por padrão, apenas erros 5xx são incluídos — adicione `include_4xx=true` para incluir os 4xx.

```go theme={null}
errs, err := api.GetApplicationNetworkErrors(
	"abc123def456abc123def456",
	start, end,
	rest.WithQueryParam("include_4xx", "true"),
)
if err != nil {
	panic(err)
}
```

## Logs por requisição

`api.GetApplicationNetworkLogs(appID, start, end)` retorna os logs por requisição da edge.

```go theme={null}
logs, err := api.GetApplicationNetworkLogs("abc123def456abc123def456", start, end)
if err != nil {
	panic(err)
}
```

<Note>
  Logs por requisição exigem o plano [Pro](https://squarecloud.app/plans) ou superior.
</Note>

## Percentis de latência

`api.GetApplicationNetworkPerformance(appID, start, end)` retorna as latências p50 / p95 / p99 para as camadas edge e origin.

```go theme={null}
perf, err := api.GetApplicationNetworkPerformance("abc123def456abc123def456", start, end)
if err != nil {
	panic(err)
}
```

<Note>
  Métricas de performance exigem o plano [Pro](https://squarecloud.app/plans) ou superior.
</Note>

## Limpando o cache da edge

`api.PurgeApplicationCache(appID)` invalida o cache inteiro da edge para os domínios da aplicação.

```go theme={null}
err := api.PurgeApplicationCache("abc123def456abc123def456")
if err != nil {
	panic(err)
}
```

## Domínios e load balancers de toda a conta

Esses dois métodos operam sobre todas as aplicações da conta, não apenas um único site.

### Listando todos os domínios

`api.GetApplicationDomains()` retorna todos os domínios configurados em todas as aplicações da conta como um `[]squarecloud.AppDomain`. Domínios customizados são listados primeiro; aplicações sem domínio web são omitidas.

```go theme={null}
domains, err := api.GetApplicationDomains()
if err != nil {
	panic(err)
}

for _, domain := range domains {
	fmt.Println(domain.AppID, domain.Hostname, domain.Type) // "subdomain" | "custom"
}
```

### Load balancers

`api.GetLoadBalancers()` agrupa aplicações que compartilham um domínio customizado, retornando um `squarecloud.LoadBalancers`.

```go theme={null}
lb, err := api.GetLoadBalancers()
if err != nil {
	panic(err)
}

fmt.Println("limite do plano:", lb.Limit)
for _, balancer := range lb.Balancers {
	fmt.Println(balancer.Hostname, len(balancer.Apps), "apps")
}
```

Um grupo com 2 ou mais apps é um load balancer ativo: o tráfego é balanceado na edge com failover automático quando um dos apps está offline. `Limit` é o número máximo de aplicações que podem compartilhar um domínio no plano da conta: 2 (Standard), 5 (Pro), 10 (Enterprise).