> ## 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.

# Rete ed edge

> Gestisci domini personalizzati, DNS, analytics edge, tracciamento degli errori, log delle richieste, percentili di latenza e invalidazione della cache per le applicazioni sito web.

<Note>
  Gli endpoint di questa pagina si applicano solo alle **applicazioni sito web** — app con un dominio web. Chiamarli su un'applicazione non web fallisce.
</Note>

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

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

## Dominio personalizzato

`api.SetApplicationCustomDomain(appID, domain)` imposta il dominio personalizzato associato al sito web.

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

## Record DNS

Dopo aver collegato un dominio personalizzato devi configurare il DNS presso il tuo registrar. `api.GetApplicationDNS(appID)` restituisce i record da creare come `[]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     | Descrizione                                                                                                                                                          |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Type`   | `string` | `"txt"` oppure `"cname"` — i record TXT coprono la verifica di proprietà e la validazione SSL; il CNAME trasporta il traffico e punta sempre a `cname.squareweb.app` |
| `Name`   | `string` | Nome del record da creare                                                                                                                                            |
| `Value`  | `string` | Valore del record                                                                                                                                                    |
| `Status` | `string` | Stato di validazione: `"pending"`, `"pending_validation"` oppure `"active"`                                                                                          |

## Analytics

`api.GetApplicationAnalytics(appID, start, end)` restituisce le analytics edge aggregate per la finestra indicata come `squarecloud.NetworkAnalytics`. La finestra è obbligatoria e la retention massima è di **7 giorni**.

```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), "time buckets") // 15-minute series
fmt.Println(analytics.Countries)
fmt.Println(analytics.Paths)
```

La risposta contiene serie temporali a 15 minuti (`Visits`, `Countries`, `Devices`, `OS`, `Browsers`, `Protocols`, `Methods`, `Paths`, `Referers`, `Providers`) e bucket sull'intera finestra (`IPs`, `StatusCodes`, `Bots`, `ContentTypes`).

<Note>
  Per una finestra interamente precedente alla creazione dell'applicazione, l'API restituisce un oggetto vuoto — ogni slice della risposta è `nil`. Controlla le lunghezze prima di indicizzare.
</Note>

### Filtri di drill-down

Oltre alla finestra, l'endpoint accetta filtri opzionali come parametri di query — passali con `rest.WithQueryParam`. Ogni filtro restringe contemporaneamente ogni ripartizione della risposta:

| Filtro         | Note                                                     |
| -------------- | -------------------------------------------------------- |
| `country`      | Codice paese a 2 lettere, ad esempio `"BR"`              |
| `ip`           | Corrispondenza esatta dell'IP                            |
| `path`         | Corrispondenza per prefisso, ad esempio `"/api"`         |
| `status`       | Codice di stato HTTP, ad esempio `"404"`                 |
| `os`           | Sistema operativo                                        |
| `browser`      | Nome del browser                                         |
| `protocol`     | Protocollo della richiesta                               |
| `referer`      | Usa `"Direct"` per le richieste senza referer            |
| `provider`     | Provider di rete, ad esempio `"GOOGLE (15169)"` (ASN)    |
| `content_type` | Usa `"Unknown"` per i tipi di contenuto non classificati |
| `bot`          | Usa `"Unverified"` per il traffico normale (non bot)     |

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

## Tracciamento degli errori

`api.GetApplicationNetworkErrors(appID, start, end)` restituisce la ripartizione degli errori edge. Per impostazione predefinita sono inclusi solo gli errori 5xx — aggiungi `include_4xx=true` per includere i 4xx.

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

## Log per richiesta

`api.GetApplicationNetworkLogs(appID, start, end)` restituisce i log edge per singola richiesta.

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

<Note>
  I log per richiesta richiedono un [piano Pro](https://squarecloud.app/plans) o superiore.
</Note>

## Percentili di latenza

`api.GetApplicationNetworkPerformance(appID, start, end)` restituisce le latenze p50 / p95 / p99 per i livelli edge e origin.

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

<Note>
  Le metriche di performance richiedono un [piano Pro](https://squarecloud.app/plans) o superiore.
</Note>

## Svuotare la cache edge

`api.PurgeApplicationCache(appID)` invalida l'intera cache edge per i domini dell'applicazione.

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

## Domini e load balancer a livello di account

Questi due metodi operano su tutte le applicazioni dell'account, non su un singolo sito web.

### Elencare tutti i domini

`api.GetApplicationDomains()` restituisce ogni dominio configurato tra tutte le applicazioni dell'account come `[]squarecloud.AppDomain`. I domini personalizzati sono elencati per primi; le applicazioni senza dominio web vengono omesse.

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

`api.GetLoadBalancers()` raggruppa le applicazioni che condividono un dominio personalizzato, restituendo un `squarecloud.LoadBalancers`.

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

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

Un gruppo con 2 o più app è un load balancer attivo: il traffico viene bilanciato all'edge con failover automatico quando una delle app è offline. `Limit` è il numero massimo di applicazioni che possono condividere un dominio con il piano dell'account: 2 (Standard), 5 (Pro), 10 (Enterprise).