Home / Docs / Congestion Insights / Congestion notifications

Congestion notifications

With the Congestion capability insights, an application can determine if the geographic area where the mobile device is located is going to experience congestion that might affect use cases such as bandwidth or latency. This way, the app might proactively move functionality to another area or use functionalities, such as QoD or Network Slicing to avoid congestion.

You can learn how to subscribe to Congestion notifications or unsubscribe from them below, so you can stay up to date with congestion levels for multiple devices.

TIP: Read more about the notification URL/auth token and how to create an HTTP server with a POST endpoint for congestion notifications.

Subscribing to Congestion notificationsheader link

With this snippet, you can subscribe to notifications for Congestion level changes and receive congestion updates using the subscribe_to_congestion_info method. It passes the device information, subscription expiration time, notification URL, and notification authentication token as parameters. The method returns a subscription object. It also prints the ID of the subscription which you can use for management purposes.

import network_as_code as nac

from datetime import datetime, timezone, timedelta

from network_as_code.models.device import DeviceIpv4Addr

# Create a client and device objects as previously shown
client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

my_device = client.devices.get(
    "[email protected]",
    ipv4_address=DeviceIpv4Addr(
        public_address="192.0.2.3",
        private_address="192.0.2.204",
        public_port=80
    ),
    ipv6_address="2001:db8:1234:5678:9abc:def0:fedc:ba98",
    phone_number="+36721601234567"
)

# Subscribe your device to Congestion notifications
congestion_subscription = client.insights.subscribe_to_congestion_info(
    my_device,
    # Set the duration of your subscription to congestion insights,
    # e.g.: it can end in `n` days starting from now.
    subscription_expire_time=datetime.now(timezone.utc) + timedelta(days=1),
    # Set a notification URL with auth token to receive updates
    notification_url="https://example.com/notify",
    notification_auth_token="my-secret-token",
)

# Subscriptions are identified by id, for management
# Use this to show the subscription:
print(congestion_subscription.id)

# Or check when your subscription starts/expires:
print(congestion_subscription.starts_at)
print(congestion_subscription.expires_at)

NOTE: Learn how to get a list of subscriptions created for a device using this tutorial.

Congestion level notification handlerheader link

# congestion_handler.py

# run with: uvicorn congestion_handler:app

from fastapi import FastAPI, Header
from pydantic import BaseModel

from typing_extensions import Annotated
from typing import Union

app = FastAPI()

class Data(BaseModel):
    level: str

class Notification(BaseModel):
    id: str
    source: str
    type: str
    specversion: str
    datacontenttype: str
    time: str
    data: Data

@app.post("/notifications")
def receive_notification(
    notification: Notification,
    authorization: Annotated[Union[str, None], Header]
):
    if authorization == "Bearer my-secret-token":
        # We can now react to the notifications
        # based on the Notification object
        print(notification)

Unsubscribing from congestion notificationsheader link

Finally, the code shows how to stop a subscription by calling the delete method. You simply call the delete() method with your congestion subscription object to delete it.

# Use the congestion_subscription object previously created
# and delete it to stop receiving notifications:
congestion_subscription.delete()

Congestion notifications parametersheader link

Parameters	Type	Description	Mandatory or Optional
`my_device`	object	Information about the device for which congestion data is requested or subscribed to.	Mandatory
`subscription_expire_time`	object/string	Expiration time for the congestion subscription. Can be either a date-time object or ISO 8601 formatted date string.	Mandatory
`notification_url`	string	URL where notifications about congestion updates will be sent.	Mandatory
`notification_auth_token`	string	Authentication token for accessing the notification URL.	Optional

Last updated November 05, 2025