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

# Red

> Consulta las analíticas del edge, los errores, los logs de peticiones y el rendimiento de una aplicación web, comprueba el DNS, configura un dominio personalizado y purga la caché con client.apps.network.

`client.apps.network` funciona **solo con aplicaciones web**. Todos los métodos reciben primero el id de la aplicación.

## Ventanas de tiempo

`analytics`, `errors`, `logs` y `performance` reciben un `start` y un `end`, cada uno un string ISO 8601 o un `datetime`. Un `datetime` naive es hora local, convertida a UTC. Una ventana abarca como máximo **7 días**, y `start` se ajusta a la fecha de creación de la aplicación. Una ventana no válida da 400 `INVALID_TIME_RANGE`.

```python theme={"system"}
from datetime import UTC, datetime, timedelta

end = datetime.now(UTC)
start = end - timedelta(hours=24)  # last 24 h
```

Los resultados se almacenan en caché en intervalos de 5 minutos. Los fallos de caché de estos cuatro métodos comparten un límite de 20 peticiones cada 60 segundos por cuenta: superarlo da 429 `RATE_LIMITED`.

## Analíticas

`network.analytics(app_id, start, end, **filters)` devuelve los totales de tráfico y sus desgloses. Devuelve `None` para una ventana sin tráfico.

```python theme={"system"}
analytics = client.apps.network.analytics(app_id, start, end)

if analytics:
    print(analytics["visits"])     # [{'visits', 'requests', 'bytes', 'date'}]
    print(analytics["countries"])  # [{'type': 'BR', 'visits', 'requests', 'bytes'}]
```

Los desgloses son `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` y `content_types`. Cada grupo tiene `type`, `visits`, `requests` y `bytes`.

### Filtros

Los filtros son argumentos por palabra clave y acotan todos los desgloses. Cada uno recibe el valor exacto de `type` de su desglose:

```python theme={"system"}
brazil = client.apps.network.analytics(
    app_id,
    start,
    end,
    country="BR",
    path="/api",
    provider="GOOGLE (15169)",
)
```

| Filtro                             | Ejemplo                                   |
| ---------------------------------- | ----------------------------------------- |
| `country`                          | `"BR"` (código de 2 letras)               |
| `ip`                               | `"203.0.113.7"`                           |
| `path`                             | `"/api"` (prefijo de ruta)                |
| `status`                           | `"404"`                                   |
| `os`, `browser`, `protocol`, `bot` | El `type` del desglose                    |
| `referer`                          | `"Direct"` significa sin referer          |
| `provider`                         | `"NAME (ASN)"`, p. ej. `"GOOGLE (15169)"` |
| `content_type`                     | El `type` del desglose                    |

Un filtro no válido da 400 `INVALID_FILTER`. Un filtro establecido en `None` o `''` no se envía.

## Errores

`network.errors(app_id, start, end, include_4xx=False)` devuelve las respuestas 5xx de la ventana, más las 4xx con `include_4xx=True` (solo por palabra clave). Devuelve `None` para una ventana vacía.

```python theme={"system"}
errors = client.apps.network.errors(app_id, start, end, include_4xx=True)

if errors:
    print(errors["summary"]["total"], errors["summary"]["by_class"])
    print(errors["top_paths"])
```

## Logs de peticiones

`network.logs(app_id, start, end)` devuelve peticiones individuales con detalles del cliente, la petición y la respuesta. Disponible en los planes Pro y Enterprise (en caso contrario, 403 `UPGRADE_REQUIRED`).

```python theme={"system"}
for log in client.apps.network.logs(app_id, start, end):
    print(log["timestamp"], log["request"]["method"], log["request"]["path"], log["response"]["status"])
```

## Rendimiento

`network.performance(app_id, start, end)` devuelve percentiles de latencia (`p50`, `p95`, `p99`, en ms) en el edge y en el origen, por país, por ubicación y para las rutas más lentas. Devuelve `None` para una ventana vacía. Disponible en los planes Pro y Enterprise.

```python theme={"system"}
performance = client.apps.network.performance(app_id, start, end)

if performance:
    print(performance["summary"]["edge"]["p95"], performance["summary"]["origin"]["p95"])
```

## DNS

`network.dns(app_id)` devuelve los registros DNS que necesita tu dominio personalizado, con su estado. Sin un dominio personalizado da 400 `NO_CUSTOM_DOMAIN`.

```python theme={"system"}
for record in client.apps.network.dns(app_id):
    print(record["type"], record["name"], record["value"], record["status"])  # type: "txt" | "cname"
```

## Dominio personalizado

`network.set_domain(app_id, domain)` asocia un dominio personalizado (plan Standard o superior). Pasa `"@"` para eliminarlo.

```python theme={"system"}
client.apps.network.set_domain(app_id, "www.example.com")

# Remove it
client.apps.network.set_domain(app_id, "@")
```

| Estado | Código                        | Cuándo                                                        |
| ------ | ----------------------------- | ------------------------------------------------------------- |
| 400    | `INVALID_DOMAIN`              | No es un nombre de dominio válido                             |
| 400    | `RESERVED_DOMAIN`             | Un dominio de Square Cloud                                    |
| 403    | `UPGRADE_REQUIRED`            | El plan no incluye dominios personalizados                    |
| 403    | `LOAD_BALANCER_LIMIT_REACHED` | Se alcanzó el límite del plan de aplicaciones en este dominio |
| 409    | `DOMAIN_ALREADY_EXISTS`       | El dominio pertenece a una aplicación de otra cuenta          |
| 502    | `DNS_FAILED`                  | El proveedor del edge rechazó el dominio                      |

## Purgar la caché

`network.purge_cache(app_id)` borra la caché del edge de la aplicación. Está limitado a una purga cada 60 segundos (429 `KEEP_CALM`).

```python theme={"system"}
client.apps.network.purge_cache(app_id)
```

## Errores de los métodos de analíticas

| Estado | Código                                                                               | Cuándo                                                               |
| ------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| 400    | `INVALID_TIME_RANGE`                                                                 | `start`/`end` ausente, mal formado o invertido                       |
| 400    | `INVALID_FILTER`                                                                     | Un filtro no respeta su formato (`analytics`)                        |
| 403    | `UPGRADE_REQUIRED`                                                                   | `logs` y `performance` fuera de Pro y Enterprise                     |
| 429    | `RATE_LIMITED`                                                                       | Se alcanzó el límite compartido de fallos de caché                   |
| 500    | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | Falló el proveedor del edge                                          |
| 503    | `ANALYTICS_BUSY`                                                                     | Las analíticas del edge están ocupadas: se reintenta automáticamente |