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

# Netzwerk

> Lies Edge-Analytics, Fehler, Request-Logs und Performance einer Webanwendung, prüfe DNS, lege eine eigene Domain fest und leere den Cache mit client.apps.network.

`client.apps.network` funktioniert **nur mit Web-Apps**. Jede Methode nimmt zuerst die App-ID.

## Zeitfenster

`analytics`, `errors`, `logs` und `performance` nehmen ein `start` und ein `end`, jeweils ein ISO-8601-String oder ein `datetime`. Ein naives `datetime` gilt als lokale Zeit und wird in UTC umgerechnet. Ein Fenster umfasst höchstens **7 Tage**, und `start` wird auf das Erstellungsdatum der App begrenzt. Ein ungültiges Fenster ergibt 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
```

Ergebnisse werden in 5-Minuten-Intervallen gecacht. Cache-Misses dieser vier Methoden teilen sich ein Limit von 20 Anfragen pro 60 Sekunden pro Konto: Wird es überschritten, ergibt das 429 `RATE_LIMITED`.

## Analytics

`network.analytics(app_id, start, end, **filters)` gibt Verkehrssummen und Aufschlüsselungen zurück. Für ein Fenster ohne Verkehr gibt die Methode `None` zurück.

```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'}]
```

Die Aufschlüsselungen sind `countries`, `devices`, `os`, `browsers`, `protocols`, `methods`, `paths`, `referers`, `providers`, `ips`, `status_codes`, `bots` und `content_types`. Jeder Eintrag hat `type`, `visits`, `requests` und `bytes`.

### Filter

Filter sind Keyword-Argumente und schränken jede Aufschlüsselung ein. Jeder nimmt den exakten `type`-Wert seiner Aufschlüsselung:

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

| Filter                             | Beispiel                                 |
| ---------------------------------- | ---------------------------------------- |
| `country`                          | `"BR"` (Code aus 2 Buchstaben)           |
| `ip`                               | `"203.0.113.7"`                          |
| `path`                             | `"/api"` (Pfadpräfix)                    |
| `status`                           | `"404"`                                  |
| `os`, `browser`, `protocol`, `bot` | Der `type` der Aufschlüsselung           |
| `referer`                          | `"Direct"` bedeutet kein Referer         |
| `provider`                         | `"NAME (ASN)"`, z. B. `"GOOGLE (15169)"` |
| `content_type`                     | Der `type` der Aufschlüsselung           |

Ein ungültiger Filter ergibt 400 `INVALID_FILTER`. Ein Filter mit dem Wert `None` oder `''` wird nicht gesendet.

## Fehler

`network.errors(app_id, start, end, include_4xx=False)` gibt die 5xx-Antworten des Fensters zurück, mit `include_4xx=True` (reines Keyword-Argument) zusätzlich die 4xx. Für ein leeres Fenster gibt die Methode `None` zurück.

```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"])
```

## Request-Logs

`network.logs(app_id, start, end)` gibt einzelne Anfragen mit Details zu Client, Anfrage und Antwort zurück. Verfügbar in den Plänen Pro und Enterprise (sonst 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"])
```

## Performance

`network.performance(app_id, start, end)` gibt Latenzperzentile (`p50`, `p95`, `p99`, in ms) an der Edge und am Ursprung zurück, nach Land, nach Standort und für die langsamsten Pfade. Für ein leeres Fenster gibt die Methode `None` zurück. Verfügbar in den Plänen Pro und 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)` gibt die DNS-Einträge zurück, die deine eigene Domain benötigt, zusammen mit ihrem Status. Ohne eigene Domain ergibt das 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"
```

## Eigene Domain

`network.set_domain(app_id, domain)` verbindet eine eigene Domain (ab dem Standard-Plan). Übergib `"@"`, um sie zu entfernen.

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

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

| Status | Code                          | Wann                                                          |
| ------ | ----------------------------- | ------------------------------------------------------------- |
| 400    | `INVALID_DOMAIN`              | Kein gültiger Domainname                                      |
| 400    | `RESERVED_DOMAIN`             | Eine Domain von Square Cloud                                  |
| 403    | `UPGRADE_REQUIRED`            | Der Plan hat keine eigenen Domains                            |
| 403    | `LOAD_BALANCER_LIMIT_REACHED` | Das Limit des Plans für Apps auf dieser Domain wurde erreicht |
| 409    | `DOMAIN_ALREADY_EXISTS`       | Die Domain gehört zu einer App eines anderen Kontos           |
| 502    | `DNS_FAILED`                  | Der Edge-Anbieter hat die Domain abgelehnt                    |

## Cache leeren

`network.purge_cache(app_id)` leert den Edge-Cache der App. Das ist auf einen Vorgang alle 60 Sekunden begrenzt (429 `KEEP_CALM`).

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

## Fehler der Analytics-Methoden

| Status | Code                                                                                 | Wann                                                             |
| ------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
| 400    | `INVALID_TIME_RANGE`                                                                 | `start`/`end` fehlt, ist fehlerhaft oder vertauscht              |
| 400    | `INVALID_FILTER`                                                                     | Ein Filter entspricht nicht seinem Format (`analytics`)          |
| 403    | `UPGRADE_REQUIRED`                                                                   | `logs` und `performance` außerhalb von Pro und Enterprise        |
| 429    | `RATE_LIMITED`                                                                       | Gemeinsames Limit für Cache-Misses erreicht                      |
| 500    | `UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE` | Der Edge-Anbieter ist fehlgeschlagen                             |
| 503    | `ANALYTICS_BUSY`                                                                     | Die Edge-Analytics sind ausgelastet: wird automatisch wiederholt |