Python SDK: analytics, DNS and domains

client.apps.network works on web apps only. Every method takes the app id first. Examples use the client from Creating the client. app_id is the id of one of your apps: client.account.me() lists them.

Time windows

analytics, errors, logs and performance take a start and an end, each an ISO 8601 string or a datetime. A naive datetime is local time, converted to UTC. A window is at most 7 days, and start is clamped to the app’s creation date. An invalid window is 400 INVALID_TIME_RANGE.

from datetime import UTC, datetime, timedelta

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

Results are cached in 5-minute buckets. Cache misses of these four methods share a limit of 20 requests per 60 seconds per account: going over it is 429 RATE_LIMITED.

Analytics

network.analytics(app_id, start, end, **filters) returns traffic totals and breakdowns. It returns None for a window with no traffic.

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

The breakdowns are countries, devices, os, browsers, protocols, methods, paths, referers, providers, ips, status_codes, bots and content_types. Each bucket has type, visits, requests and bytes.

Filters

Filters are keyword arguments and narrow every breakdown. Each takes the exact type value of its breakdown:

brazil = client.apps.network.analytics(
    app_id,
    start,
    end,
    country="BR",
    path="/api",
    provider="GOOGLE (15169)",
)

Filter	Example
`country`	`"BR"` (2-letter code)
`ip`	`"203.0.113.7"`
`path`	`"/api"` (path prefix)
`status`	`"404"`
`os`, `browser`, `protocol`, `bot`	The breakdown’s `type`
`referer`	`"Direct"` means no referer
`provider`	`"NAME (ASN)"`, e.g. `"GOOGLE (15169)"`
`content_type`	The breakdown’s `type`

An invalid filter is 400 INVALID_FILTER. A filter set to None or '' is not sent.

Errors

network.errors(app_id, start, end, include_4xx=False) returns the 5xx responses of the window, plus 4xx with include_4xx=True (keyword-only). It returns None for an empty window.

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) returns individual requests with client, request and response details. Available on Pro and Enterprise plans (403 UPGRADE_REQUIRED otherwise).

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) returns latency percentiles (p50, p95, p99, in ms) at the edge and at the origin, by country, by location and for the slowest paths. It returns None for an empty window. Available on Pro and Enterprise plans.

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) returns the DNS records your custom domain needs, with their status. Without a custom domain it is 400 NO_CUSTOM_DOMAIN.

for record in client.apps.network.dns(app_id):
    print(record["type"], record["name"], record["value"], record["status"])  # type: "txt" | "cname"

Custom domain

network.set_domain(app_id, domain) attaches a custom domain (Standard plan and up). Pass "@" to remove it.

client.apps.network.set_domain(app_id, "www.example.com")

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

Status	Code	When
400	`INVALID_DOMAIN`	Not a valid domain name
400	`RESERVED_DOMAIN`	A Square Cloud domain
403	`UPGRADE_REQUIRED`	The plan has no custom domains
403	`LOAD_BALANCER_LIMIT_REACHED`	The plan’s limit of apps on this domain was reached
409	`DOMAIN_ALREADY_EXISTS`	The domain belongs to an app of another account
502	`DNS_FAILED`	The edge provider refused the domain

Purging the cache

network.purge_cache(app_id) clears the app’s edge cache. It is limited to one purge every 60 seconds (429 KEEP_CALM).

client.apps.network.purge_cache(app_id)

Errors of the analytics methods

Status	Code	When
400	`INVALID_TIME_RANGE`	`start`/`end` missing, malformed or inverted
400	`INVALID_FILTER`	A filter does not match its format (`analytics`)
403	`UPGRADE_REQUIRED`	`logs` and `performance` outside Pro and Enterprise
429	`RATE_LIMITED`	Shared limit of cache misses reached
500	`UNABLE_TO_FETCH_ANALYTICS`, `UNABLE_TO_FETCH_ERRORS`, `UNABLE_TO_FETCH_PERFORMANCE`	The edge provider failed
503	`ANALYTICS_BUSY`	Edge analytics are busy: retried automatically

Next steps

Realtime

Stream live logs and status.

Network API reference

The REST endpoints behind these methods.

Edge analytics from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

Python SDK: analytics, DNS and domains

Time windows

Analytics

Filters

Errors

Request logs

Performance

DNS

Custom domain

Purging the cache

Errors of the analytics methods

Next steps

Realtime

Network API reference

Edge analytics from the CLI

​Time windows

​Analytics

​Filters

​Errors

​Request logs

​Performance

​DNS

​Custom domain

​Purging the cache

​Errors of the analytics methods

​Next steps

Realtime

Network API reference

Edge analytics from the CLI

Time windows

Analytics

Filters

Errors

Request logs

Performance

DNS

Custom domain

Purging the cache

Errors of the analytics methods

Next steps