### Initialize and Make a Central API Call

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/index.md

This example demonstrates how to initialize the NewCentralBase class with token credentials and make a GET request to the network-monitoring devices API. It includes basic error handling for the API response.

```python
from pycentral import NewCentralBase

central_credential = {
   "new_central": {
       "base_url": "https://us5.api.central.arubanetworks.com",
       "client_id": "client_id",
       "client_secret": "client_secret",
   }
}

# Initialize NewCentralBase class with the token credentials for Central/GLP
central_conn = NewCentralBase(token_info=central_credential)

# Central API Call
central_resp = central_conn.command(
    api_method="GET", api_path="network-monitoring/v1/devices"
)

# Check response status and print results or error message
if central_resp["code"] == 200:
    print(central_resp["msg"])
else:
    print(f"Error - Response code {central_resp['code']}")
    print(central_resp["msg"])

```

--------------------------------

### Example Token Configuration File

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/README.md

Example structure for a token.yaml file used for authentication. Includes configurations for both New Central and GLP.

```yaml
new_central:
  base_url: <api-base-url>
  client_id: <client-id>
  client_secret: <client-secret>
glp:
  client_id: <client-id>
  client_secret: <client-secret>
```

--------------------------------

### Install PyCentral Pre-release

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/README.md

Use this command to install the latest pre-release version of PyCentral. If upgrading from v1, use the --upgrade flag.

```bash
pip3 install --pre pycentral
```

```bash
pip3 install --upgrade --pre pycentral
```

--------------------------------

### Install Latest PyCentral Pre-release

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/getting-started/installation.md

Use this command to install the latest pre-release version of PyCentral. Ensure pip3 is available on your system.

```bash
pip3 install --pre pycentral
```

--------------------------------

### Get Wired Clients

Source: https://context7.com/aruba/pycentral/llms.txt

A convenience wrapper that filters `get_all_clients()` to return only wired clients.

```python
wired = Clients.get_wired_clients(conn, site_name="Branch Office")
```

--------------------------------

### Python Script to Get Devices from New Central

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/getting-started/quickstart.md

This Python script initializes the PyCentral SDK using credentials from `token.yaml` and fetches a list of devices from New Central. Ensure the `token.yaml` file is in the same directory.

```python
import os
from pycentral import NewCentralBase

# Validate token file exists
token_file = "token.yaml"
if not os.path.exists(token_file):
    raise FileNotFoundError(
        f"Token file '{token_file}' not found. Please provide a valid token file."
    )

# Initialize NewCentralBase class with the token credentials for New Central/GLP
new_central_conn = NewCentralBase(token_info=token_file)

# New Central API Call
new_central_resp = new_central_conn.command(
    api_method="GET", api_path="network-monitoring/v1/devices"
)

# Check response status and print results or error message
if new_central_resp["code"] == 200:
    print(new_central_resp["msg"])
else:
    print(f"Error - Response code {new_central_resp['code']}")
    print(new_central_resp["msg"])

```

--------------------------------

### Get All Clients with Auto-Pagination

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches the complete list of network clients (wired and wireless), handling pagination automatically. Supports filtering, sorting, and time-bounded queries.

```python
from pycentral.new_monitoring import Clients

# All clients
all_clients = Clients.get_all_clients(conn)
# [{"clientMac": "aa:bb:cc:dd:ee:ff", "clientConnectionType": "Wireless", "status": "Connected"}, ...]

# Clients at a specific site in the past 3 hours
clients = Clients.get_all_clients(
    conn,
    site_name="HQ Campus",
    duration="3h",
    sort="clientMac asc",
)
```

--------------------------------

### Get Wireless Clients

Source: https://context7.com/aruba/pycentral/llms.txt

A convenience wrapper that filters `get_all_clients()` to return only wireless clients.

```python
wireless = Clients.get_wireless_clients(conn, site_id="site-uuid-1234")
# [{"clientMac": "aa:bb:cc:dd:ee:ff", "ssid": "Corp-WiFi", "band": "5GHz", ...}, ...]
```

--------------------------------

### Get Connected Clients

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves a list of all currently connected clients for a given site. Requires a connection object and a site ID.

```python
connected = Clients.get_connected_clients(conn, site_id="site-uuid-1234")
```

--------------------------------

### Clients.get_client_details()

Source: https://context7.com/aruba/pycentral/llms.txt

Get details for a specific client by MAC address. Fetches comprehensive details for a single client using the `GET network-monitoring/v1/clients/{client_mac}` endpoint.

```APIDOC
## Clients.get_client_details()

### Description
Fetches full details for a single client from `GET network-monitoring/v1/clients/{client_mac}`.

### Parameters
- **conn**: Connection object
- **client_mac** (string) - Required - The MAC address of the client.

### Request Example
```python
client = Clients.get_client_details(conn, client_mac="aa:bb:cc:dd:ee:ff")
# {"clientMac": "aa:bb:cc:dd:ee:ff", "ipAddress": "10.0.0.100", "ssid": "Corp-WiFi", ...}
```
```

--------------------------------

### Get Gateway Interfaces

Source: https://context7.com/aruba/pycentral/llms.txt

Returns port-level details for a gateway.

```python
ports = MonitoringGateways.get_gateway_interfaces(conn, serial_number="GW001")
# {"items": [{"name": "0/0/0", "speed": "1G", "status": "Up"}, ...]}}
```

--------------------------------

### Make New Central API Call for a Tenant

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/modules/msp.md

Use `MSPBase` to get a tenant connection and then make new Central API calls within that tenant's workspace. Ensure `token_info` is correctly configured.

```python
from pycentral import MSPBase

with MSPBase(token_info="account_credentials_new.yaml") as msp:
        tenant_conn = msp.get_tenant_connection(tenant_workspace_id="<tenant-workspace-id>")

        # List APs in the tenant's Central environment
        response = tenant_conn.command(
            api_method="GET",
            api_path="network-monitoring/v1/aps",
        )
        if response["code"] == 200:
            aps = response["msg"].get("items", [])
            print(f"Tenant APs: {len(aps)}")
            for ap in aps:
                print(ap.get("serialNumber"), ap.get("deviceName"), ap.get("status"))
        else:
            print(f"Error {response['code']}: {response['msg']}")
```

--------------------------------

### Get Top-N Interface Trends for a Site

Source: https://context7.com/aruba/pycentral/llms.txt

Returns the top bandwidth-consuming switch interfaces for a site over a specified time window. Requires site ID and duration.

```python
topn = MonitoringSwitches.get_topn_interface_trends(
    conn, site_id="site-uuid-1234", duration="3h"
)
```

--------------------------------

### Get Top N Clients by Data Usage

Source: https://context7.com/aruba/pycentral/llms.txt

Returns the top bandwidth-consuming clients for a specified time window. Requires a connection object, site name, limit for the number of clients, and duration.

```python
top_clients = Clients.get_top_n_clients(
    conn, site_name="HQ Campus", limit=10, duration="24h"
)
```

--------------------------------

### Get All Gateways with Auto-Pagination

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches the complete list of gateways managed by the account, automatically handling pagination. Supports filtering and sorting.

```python
from pycentral.new_monitoring import MonitoringGateways

gateways = MonitoringGateways.get_all_gateways(conn)
# [{"serialNumber": "GW001", "model": "9004", "status": "Up"}, ...]

gateways = MonitoringGateways.get_all_gateways(
    conn, filter_str="status eq 'Up'", sort="serialNumber"
)
```

--------------------------------

### Get Gateway Stats (CPU, Memory, WAN Availability)

Source: https://context7.com/aruba/pycentral/llms.txt

Collects gateway CPU utilization, memory utilization, and WAN availability trends in parallel. Returns a merged, timestamp-sorted list.

```python
stats = MonitoringGateways.get_gateway_stats(
    conn, serial_number="GW001", duration="6h"
)
# [{"timestamp": 1710000000, "cpu_utilization": 20, "memory_utilization": 55, "wan_availability": 100}, ...]
```

--------------------------------

### Unified Credentials for GLP + New Central

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/getting-started/authentication.md

Configure unified credentials for both GLP and New Central API access. This example includes the cluster name to identify the New Central API gateway.

```python
token_info = {
    "unified": {
        "client_id": "<glp-client-id>",
        "client_secret": "<glp-client-secret>",
        "workspace_id": "<workspace-id>",
        "cluster_name": "Internal"  # or "base_url": "https://apigw-<cluster>.central.arubanetworks.com"
    }
}
```

--------------------------------

### Get Failed Clients

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves a list of all clients with a 'Failed' status for a given site. Requires a connection object and a site name.

```python
failed = Clients.get_failed_clients(conn, site_name="Branch Office")
```

--------------------------------

### Execute Raw API Calls with NewCentralBase.command()

Source: https://context7.com/aruba/pycentral/llms.txt

Make direct API requests to Central or GreenLake Platform. Handles authentication, retries, and response parsing. Use for GET, POST, and file uploads.

```python
# GET request with query parameters
resp = conn.command(
    api_method="GET",
    api_path="monitoring/v1/aps",
    app_name="new_central",           # or "glp"
    api_params={"limit": 10, "offset": 0},
)
# resp == {"code": 200, "msg": {"items": [...], "total": 42}, "headers": {...}}

# POST request with a JSON body
resp = conn.command(
    api_method="POST",
    api_path="troubleshooting/v1/devices/CN12345678/ping",
    api_data={"destination": "8.8.8.8", "count": 5},
)
# resp == {"code": 202, "msg": {"task_id": "abc-123"}, "headers": {"location": "/task/abc-123"}}

# Multipart file upload
with open("firmware.swi", "rb") as f:
    resp = conn.command(
        api_method="POST",
        api_path="firmware/v1/upload",
        files={"file": ("firmware.swi", f, "application/octet-stream")},
    )
```

--------------------------------

### Get Client Details by MAC Address

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches full details for a single client using its MAC address. Requires a connection object and the client's MAC address.

```python
client = Clients.get_client_details(conn, client_mac="aa:bb:cc:dd:ee:ff")
# {"clientMac": "aa:bb:cc:dd:ee:ff", "ipAddress": "10.0.0.100", "ssid": "Corp-WiFi", ...}
```

--------------------------------

### Get All Devices in GLP Workspace

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves all devices within the GreenLake Platform workspace. The response is a list of dictionaries, each containing device details like ID, serial number, and model.

```python
# Get all devices in the workspace
all_devs = glp_devices.get_all_devices(conn)
# [{"id": "dev-uuid-001", "serialNumber": "SN001", "model": "AP-515"}, ...]
```

--------------------------------

### Get AP PoE Utilization Trend

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches power consumption trend data for PoE on a specific AP within a specified time range. Requires AP serial number, start time, and end time.

```python
poe = MonitoringAPs.get_ap_poe_utilization(
    conn, serial_number="CNAP0001",
    start_time=1710000000, end_time=1710003600,
)
```

--------------------------------

### Troubleshooting.run_show_commands()

Source: https://context7.com/aruba/pycentral/llms.txt

Executes one or more CLI `show` commands on the specified device and returns the output.

```APIDOC
## Troubleshooting.run_show_commands()

### Description
Executes one or more CLI `show` commands on the specified device and returns the output. Use `list_show_commands()` to discover supported commands for a device type.

### Parameters
- **central_conn**: Connection object for Aruba Central.
- **serial_number** (string): Serial number of the device.
- **commands** (list of strings): A list of CLI `show` commands to execute.
- **max_attempts** (integer, optional): Maximum number of attempts to poll for the operation status.
- **poll_interval** (integer, optional): Interval in seconds between polls.

### Response Example (Success)
```json
{
  "status": "completed",
  "results": {
    "commandOutputs": [
      {
        "command": "show version",
        "output": "..."
      },
      ...
    ]
  }
}
```
```

--------------------------------

### Get Switch Hardware Trends

Source: https://context7.com/aruba/pycentral/llms.txt

Returns CPU, memory, PoE available, PoE consumption, and total power trends for a switch or stack aggregated over a time range. Requires switch serial number and duration.

```python
trends = MonitoringSwitches.get_switch_hardware_trends(
    conn, serial_number="SWCX001", duration="3h"
)
# [{"timestamp": 1710000000, "cpu_utilization": 5, "memory_utilization": 32, ...}, ...]
```

--------------------------------

### Initialize and Connect to New Central/GLP

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/README.md

Initializes the NewCentralBase class using token credentials for New Central/GLP and establishes a connection. Ensure the token_info is correctly configured.

```python
with NewCentralBase(token_info=token_file) as conn:
    pass
```

--------------------------------

### Troubleshooting.list_show_commands()

Source: https://context7.com/aruba/pycentral/llms.txt

Returns the list of supported CLI show commands for a given device's type and model.

```APIDOC
## Troubleshooting.list_show_commands()

### Description
Returns the list of supported CLI show commands for a given device's type and model.

### Parameters
- **central_conn**: Connection object for Aruba Central.
- **serial_number** (string): Serial number of the device.

### Response Example (Success)
```json
{
  "supportedCommands": [
    "show version",
    "show interfaces",
    "show vlan",
    ...
  ]
}
```
```

--------------------------------

### Initialize NewCentralBase and Validate Token File

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/README.md

Python script to initialize the NewCentralBase class and validate the existence of the token.yaml file before proceeding.

```python
import os
from pycentral import NewCentralBase

# Validate token file exists
token_file = "token.yaml"
if not os.path.exists(token_file):
    raise FileNotFoundError(
        f"Token file '{token_file}' not found. Please provide a valid token file."
    )

```

--------------------------------

### MonitoringSites.list_site_information()

Source: https://context7.com/aruba/pycentral/llms.txt

Get health details for a specific site. Returns full health details for a given site by its integer ID, querying the `GET network-monitoring/v1/site-health/{site_id}` endpoint.

```APIDOC
## MonitoringSites.list_site_information()

### Description
Returns full health details for a specific site by integer site ID from `GET network-monitoring/v1/site-health/{site_id}`.

### Parameters
- **conn**: Connection object
- **site_id** (integer) - Required - The ID of the site.

### Request Example
```python
site = MonitoringSites.list_site_information(conn, site_id=1001)
# {"siteId": 1001, "siteName": "HQ Campus", "health": "Good", "apCount": 20, ...}
```
```

--------------------------------

### Get Details for a Specific Access Point

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches full details for a single AP by serial number from `GET network-monitoring/v1/aps/{serial_number}`. Requires the AP's serial number.

```python
ap = MonitoringAPs.get_ap_details(conn, serial_number="CNAP0001")
# {"serialNumber": "CNAP0001", "model": "AP-515", "ipAddress": "10.0.0.5", ...}
```

--------------------------------

### Initialize MSP Connection

Source: https://context7.com/aruba/pycentral/llms.txt

Extends NewCentralBase with MSP token-exchange support. Use it instead of NewCentralBase when operating as a Managed Service Provider. Requires `token_info` with MSP credentials.

```python
from pycentral import MSPBase

msp = MSPBase(
    token_info={
        "unified": {
            "client_id": "msp-client-id",
            "client_secret": "msp-client-secret",
            "workspace_id": "msp-workspace-id",
            "cluster_name": "US-WEST-5",
        }
    }
)
```

--------------------------------

### Configure Token for Authentication

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/getting-started/quickstart.md

Create a `token.yaml` file to store your API credentials. This file is required by the SDK for authentication.

```yaml
new_central:
  base_url: <api-base-url>
  client_id: <client-id>
  client_secret: <client-secret>
```

--------------------------------

### List Available Show Commands for a Device

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves a list of supported CLI `show` commands for a given device type and model. This is useful for preparing to use `run_show_commands()`.

```python
commands = Troubleshooting.list_show_commands(
    central_conn=conn,
    serial_number="SWCX001",
)
# {"supportedCommands": ["show version", "show interfaces", "show vlan", ...]}}
```

--------------------------------

### Run CLI Show Commands on a Device

Source: https://context7.com/aruba/pycentral/llms.txt

Executes one or more CLI `show` commands on a specified device and returns their output. Use `list_show_commands()` to find supported commands for a device type. Parameters include max attempts and polling interval.

```python
result = Troubleshooting.run_show_commands(
    central_conn=conn,
    serial_number="SWCX001",
    commands=["show version", "show interfaces"],
    max_attempts=15,
    poll_interval=5,
)
# {"status": "completed", "results": {"commandOutputs": [{"command": "show version", "output": "..."}, ...]}}
```

--------------------------------

### Get Gateway LAN Tunnels

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves LAN tunnel configuration and status for a gateway.

```python
tunnels = MonitoringGateways.get_gateway_lan_tunnels(conn, serial_number="GW001")
```

--------------------------------

### Configuration

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/modules/classic.md

Manage configuration settings.

```APIDOC
## Configuration
::: pycentral.classic.configuration
```

--------------------------------

### Get Cluster Leader Details

Source: https://context7.com/aruba/pycentral/llms.txt

Returns details for the leader device of a named gateway cluster.

```python
leader = MonitoringGateways.get_cluster_leader_details(conn, cluster_name="HQ-Cluster")
# {"serialNumber": "GW001", "clusterName": "HQ-Cluster", "role": "leader", ...}
```

--------------------------------

### Get Gateway Details

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches full details for a single gateway using its serial number.

```python
gw = MonitoringGateways.get_gateway_details(conn, serial_number="GW001")
# {"serialNumber": "GW001", "model": "9004", "ipAddress": "192.168.1.1", ...}
```

--------------------------------

### Initialize NewCentralBase Connection

Source: https://context7.com/aruba/pycentral/llms.txt

Instantiate the core connection class with credentials. Supports dictionary or file-based credentials for standalone Central, GLP, or unified modes. Can be used as a context manager for automatic cleanup.

```python
from pycentral import NewCentralBase

# Dict-based credentials (standalone Central + GLP)
conn = NewCentralBase(
    token_info={
        "new_central": {
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "base_url": "https://apigw-prod2.central.arubanetworks.com",
        }
    }
)

# File-based credentials (YAML/JSON path — token is saved back after creation)
# conn = NewCentralBase(token_info="/path/to/credentials.yaml")

# Unified credentials (single token for both Central and GLP)
conn_unified = NewCentralBase(
    token_info={
        "unified": {
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "workspace_id": "your-glp-workspace-id",
            "cluster_name": "US-WEST-5",       # sets base_url automatically
        }
    },
    log_level="DEBUG",
    enable_scope=False,   # set True to pre-load scope/profile data at init
)

# Use as a context manager to auto-close HTTP clients
with NewCentralBase(token_info={...}) as conn:
    resp = conn.command("GET", "monitoring/v1/aps")
    print(resp["code"], resp["msg"])
```

--------------------------------

### MonitoringAPs.get_ap_details

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches full details for a single AP by serial number from `GET network-monitoring/v1/aps/{serial_number}`.

```APIDOC
## MonitoringAPs.get_ap_details

### Description
Fetches full details for a single AP by serial number from `GET network-monitoring/v1/aps/{serial_number}`.

### Method
`MonitoringAPs.get_ap_details(conn, serial_number: str) -> dict`

### Parameters
#### Path Parameters
- **conn** (Connection) - Required - The connection object.
- **serial_number** (str) - Required - The serial number of the AP.

### Response
#### Success Response (200)
- **ap** (dict) - A dictionary containing the full details of the specified AP.
```

--------------------------------

### List MSP Tenants using MSPBase

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/modules/msp.md

Perform MSP-level API calls, such as listing tenants, using the MSPBase class. Ensure 'msp_token.yaml' is correctly configured.

```python
from pycentral import MSPBase

with MSPBase(token_info="msp_token.yaml") as msp:
    # New Central API call — list MSP tenants
    response = msp.command(
            api_method="GET",
            api_path="network-msp/v1/list-tenants",
            api_params={"limit": 100, "next": 1},
    )

    if response["code"] == 200:
        tenants = response["msg"].get("items", [])
        print(f"Total tenants: {len(tenants)}")
        for tenant in tenants:
            print(f'Central Tenant ID - {tenant.get("tenantId")}, Tenant Name - {tenant.get("tenantName")}')
    else:
        print(f"Error {response['code']}: {response['msg']}")
```

--------------------------------

### Get Gateway WAN Availability Trend

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches WAN availability trend data for a specific gateway.

```python
wan = MonitoringGateways.get_gateway_wan_availability(
    conn, serial_number="GW001", duration="24h"
)
```

--------------------------------

### Get WLANs for a Specific AP

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves WLANs broadcasted by a specific AP. Supports filtering by band.

```python
result = MonitoringAPs.get_wlans(conn, serial_number="CNAP0001")
```

```python
result = MonitoringAPs.get_wlans(conn, filter_str="band eq '2.4GHz'")
```

--------------------------------

### NewCentralBase - Core Connection Class

Source: https://context7.com/aruba/pycentral/llms.txt

The `NewCentralBase` class is the primary entry point for all SDK operations. It handles authentication, token management, and provides the `command()` method for making API calls. It can be initialized with dictionary-based or file-based credentials and supports both standalone Central and GLP modes, as well as a unified mode.

```APIDOC
## NewCentralBase — Core connection class

`NewCentralBase` is the entry point for all SDK operations. It accepts credentials as a dict or a path to a YAML/JSON file, fetches an OAuth 2.0 access token via the client-credentials flow, and exposes the `command()` method used internally by every other module. Supports standalone (`new_central`), GLP (`glp`), and unified (both on one token) credential modes. Implements the context-manager protocol for deterministic HTTP-client cleanup.

```python
from pycentral import NewCentralBase

# Dict-based credentials (standalone Central + GLP)
conn = NewCentralBase(
    token_info={
        "new_central": {
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "base_url": "https://apigw-prod2.central.arubanetworks.com",
        }
    }
)

# File-based credentials (YAML/JSON path — token is saved back after creation)
# conn = NewCentralBase(token_info="/path/to/credentials.yaml")

# Unified credentials (single token for both Central and GLP)
conn_unified = NewCentralBase(
    token_info={
        "unified": {
            "client_id": "your-client-id",
            "client_secret": "your-client-secret",
            "workspace_id": "your-glp-workspace-id",
            "cluster_name": "US-WEST-5",       # sets base_url automatically
        }
    },
    log_level="DEBUG",
    enable_scope=False,   # set True to pre-load scope/profile data at init
)

# Use as a context manager to auto-close HTTP clients
with NewCentralBase(token_info={...}) as conn:
    resp = conn.command("GET", "monitoring/v1/aps")
    print(resp["code"], resp["msg"])
```
```

--------------------------------

### Get Switch Interface PoE Details

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches per-interface PoE class, status, and power consumption for a switch.

```python
poe = MonitoringSwitches.get_switch_interface_poe(conn, serial_number="SWCX001")
```

--------------------------------

### Get Switch LAG Summary

Source: https://context7.com/aruba/pycentral/llms.txt

Returns Link Aggregation Group (LAG) summary details for a specified switch.

```python
lag = MonitoringSwitches.get_switch_lag(conn, serial_number="SWCX001")
```

--------------------------------

### MonitoringSwitches.get_all_switches()

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches the complete list of switches managed by the account, handling pagination automatically.

```APIDOC
## MonitoringSwitches.get_all_switches()

### Description
Fetches the complete list of switches managed by the account, handling pagination automatically.

### Method
GET

### Endpoint
`/network-monitoring/v1/switches`

### Parameters
#### Query Parameters
- **filter_str** (string) - Optional - Filter string to apply to the switch list (e.g., "status eq 'Up' and siteId eq 'site-uuid-1234'").
- **sort** (string) - Optional - Field to sort the switch list by (e.g., "serialNumber").

### Request Example
```python
from pycentral.new_monitoring import MonitoringSwitches

switches = MonitoringSwitches.get_all_switches(conn)

# Filter by site and status
switches = MonitoringSwitches.get_all_switches(
    conn,
    filter_str="status eq 'Up' and siteId eq 'site-uuid-1234'",
    sort="serialNumber",
)
```

### Response
#### Success Response (200)
- **items** (array) - List of switches.
  - **serialNumber** (string) - The serial number of the switch.
  - **model** (string) - The model of the switch.
  - **status** (string) - The status of the switch (e.g., 'Up', 'Down').
  - **deployment** (string) - The deployment type of the switch (e.g., 'Access').

### Response Example
```json
[{"serialNumber": "SWCX001", "model": "6300M", "status": "Up", "deployment": "Access"}, ...]
```
```

--------------------------------

### Get Switch VLAN Details

Source: https://context7.com/aruba/pycentral/llms.txt

Returns VLAN membership and status for a switch or stack. Supports filtering by status.

```python
vlans = MonitoringSwitches.get_switch_vlans(
    conn, serial_number="SWCX001", filter_str="status eq 'Active'"
)
# {"items": [{"id": 10, "name": "Corp", "status": "Active", "type": "static"}, ...]}}
```

--------------------------------

### Clients.get_all_clients()

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches the complete list of network clients, handling pagination automatically. Supports filtering, sorting, and time-bounded queries.

```APIDOC
## Clients.get_all_clients()

### Description
Fetches the complete list of network clients (wired and wireless), handling pagination automatically. Supports filtering, sorting, and time-bounded queries.

### Method
```python
from pycentral.new_monitoring import Clients

# All clients
all_clients = Clients.get_all_clients(conn)
# [{"clientMac": "aa:bb:cc:dd:ee:ff", "clientConnectionType": "Wireless", "status": "Connected"}, ...]

# Clients at a specific site in the past 3 hours
clients = Clients.get_all_clients(
    conn,
    site_name="HQ Campus",
    duration="3h",
    sort="clientMac asc",
)
```
```

--------------------------------

### MonitoringAPs.get_aps

Source: https://context7.com/aruba/pycentral/llms.txt

Returns one page of AP records from `GET network-monitoring/v1/aps`. Raises `ParameterError` if `limit > 100` or `next_page < 1`.

```APIDOC
## MonitoringAPs.get_aps

### Description
Returns one page of AP records from `GET network-monitoring/v1/aps`. Raises `ParameterError` if `limit > 100` or `next_page < 1`.

### Method
`MonitoringAPs.get_aps(conn, filter_str: str = None, limit: int = 100, next_page: int = 1) -> dict`

### Parameters
#### Path Parameters
- **conn** (Connection) - Required - The connection object.
- **filter_str** (str) - Optional - A filter string to apply to the query (e.g., "status eq 'Up'").
- **limit** (int) - Optional - The maximum number of APs to return per page. Defaults to 100.
- **next_page** (int) - Optional - The page number to retrieve. Defaults to 1.

### Response
#### Success Response (200)
- **page** (dict) - A dictionary containing APs for the requested page, total count, and next page number. Example: `{"items": [...], "total": 120, "next": 2}`.
```

--------------------------------

### Troubleshooting.traceroute_cx_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates a traceroute from the specified ArubaOS-CX switch to a destination.

```APIDOC
## Troubleshooting.traceroute_cx_test()

### Description
Initiates a traceroute from the specified ArubaOS-CX switch to a destination.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - Serial number of the CX switch.
- **destination** (string) - Required - The destination IP address or hostname for the traceroute.
- **max_attempts** (integer) - Optional - Maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - Interval in seconds between polls.

### Response Example
```json
{
  "status": "completed",
  "results": {}
}
```
```

--------------------------------

### Upgrade to PyCentral V2 Pre-release

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/getting-started/installation.md

Run this command to upgrade from PyCentral V1 to the latest pre-release version of PyCentral V2. This upgrade is backward-compatible with V1.

```bash
pip3 install --upgrade --pre pycentral
```

--------------------------------

### Create Tenant Connection by Workspace ID

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/modules/msp.md

Establish a tenant-scoped connection using the tenant's GLP workspace ID. This connection behaves like NewCentralBase and is cached.

```python
from pycentral import MSPBase

with MSPBase(token_info="msp_token.yaml") as msp:
    # Option 1: Connect by tenant workspace ID (from the GLP tenant list)
    tenant_conn = msp.get_tenant_connection(tenant_workspace_id="<tenant-workspace-id>")

    # Option 2: Connect by tenant name (resolves to workspace ID via GLP API)
    # tenant_conn = msp.get_tenant_connection(tenant_name="<tenant-name>")
```

--------------------------------

### Get Switch Hardware Categories

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves detailed hardware component information for a switch using its serial number or stack ID.

```python
hw = MonitoringSwitches.get_switch_hardware_categories(conn, serial_number="SWCX001")
```

--------------------------------

### Troubleshooting.reboot_device()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates a remote reboot for the specified device and polls for completion confirmation.

```APIDOC
## Troubleshooting.reboot_device()

### Description
Initiates a remote reboot for the specified device and polls for completion confirmation.

### Parameters
- **central_conn**: Connection object for Aruba Central.
- **serial_number** (string): Serial number of the device to reboot.
- **max_attempts** (integer, optional): Maximum number of attempts to poll for the operation status.
- **poll_interval** (integer, optional): Interval in seconds between polls.

### Response Example (Success)
```json
{
  "status": "completed",
  "results": {
    "rebootStatus": "success"
  }
}
```
```

--------------------------------

### Clients.get_clients_associated_device()

Source: https://context7.com/aruba/pycentral/llms.txt

Get clients associated with a specific device. Fetches all clients linked to a particular AP, switch, or gateway using its serial number.

```APIDOC
## Clients.get_clients_associated_device()

### Description
Fetches all clients associated with a specific AP, switch, or gateway by serial number.

### Parameters
- **conn**: Connection object
- **serial_number** (string) - Required - The serial number of the device.

### Request Example
```python
device_clients = Clients.get_clients_associated_device(conn, serial_number="CNAP0001")
```
```

--------------------------------

### Run DNS Lookup from Device

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates a DNS resolution test from a specified device and polls for results.

```python
result = Troubleshooting.nslookup_test(
    central_conn=conn,
    serial_number="CNAP0001",
    hostname="example.com",
    max_attempts=10,
    poll_interval=5,
)
# {"status": "completed", "results": {"resolvedIp": "93.184.216.34"}}
```

--------------------------------

### Manage MSP and Tenant Connections with 'with' statement

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/docs/modules/msp.md

Utilize Python's `with` statement for `MSPBase` and tenant connections to ensure all HTTP clients are closed automatically upon exiting the block. This guarantees clean resource management.

```python
from pycentral import MSPBase

with MSPBase(token_info="msp_token.yaml") as msp:
    tenant_conn = msp.get_tenant_connection(tenant_workspace_id="<tenant-workspace-id>")

    # Use tenant_conn for API calls...

    # Optionally close a single tenant connection mid-session
    msp.close_tenant_connection(tenant_workspace_id="<tenant-workspace-id>")

# msp.close() is called automatically — closes MSP and all remaining tenant connections
```

--------------------------------

### Get Per-Site Device Health Statistics

Source: https://context7.com/aruba/pycentral/llms.txt

Returns the count of poor, fair, and good performing devices for each site. Requires a connection object.

```python
health = MonitoringSites.list_sites_device_health(conn)
# {"items": [{"siteId": 1001, "poor": 0, "fair": 2, "good": 40}, ...]};
```

--------------------------------

### Get Switch Stack Member Details

Source: https://context7.com/aruba/pycentral/llms.txt

Returns member-level information for a VSF/CX stack. Can be queried by stack ID or conductor serial number.

```python
members = MonitoringSwitches.get_stack_members(conn, serial_number="STACK001")
# {"items": [{"serialNumber": "SWCX001", "role": "conductor"}, {"serialNumber": "SWCX002", "role": "member"}]}
```

--------------------------------

### Execute a Python Script

Source: https://github.com/aruba/pycentral/blob/v2(pre-release)/README.md

Command to run a Python script named 'demo.py' using the python3 interpreter.

```bash
python3 demo.py
```

--------------------------------

### Get Extra Attributes for a Specific Event

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves detailed extended attributes for a given troubleshooting or audit event using its unique event ID.

```python
attrs = Troubleshooting.get_event_extra_attributes(
    central_conn=conn,
    event_id="evt-uuid-9876",
)
```

--------------------------------

### Troubleshooting.nslookup_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates a DNS resolution test from the specified device and polls for results.

```APIDOC
## Troubleshooting.nslookup_test()

### Description
Initiates a DNS resolution test from the specified device and polls for results.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - Serial number of the device.
- **hostname** (string) - Required - The hostname to perform DNS lookup on.
- **max_attempts** (integer) - Optional - Maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - Interval in seconds between polls.

### Response Example
```json
{
  "status": "completed",
  "results": {
    "resolvedIp": "93.184.216.34"
  }
}
```
```

--------------------------------

### Get Switch Details

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches full details for a specific switch, stack conductor, or stack ID. Requires the switch's serial number.

```python
sw = MonitoringSwitches.get_switch_details(conn, serial_number="SWCX001")
# {"serialNumber": "SWCX001", "model": "CX 6300M", "ipAddress": "10.0.1.1", ...}
```

--------------------------------

### Troubleshooting.iperf_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates an iPerf bandwidth test between a device and an iPerf server and polls for throughput results.

```APIDOC
## Troubleshooting.iperf_test()

### Description
Initiates an iPerf bandwidth test between a device and an iPerf server and polls for throughput results.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - Serial number of the device.
- **server_ip** (string) - Required - The IP address of the iPerf server.
- **port** (integer) - Optional - The port for the iPerf test (default is 5201).
- **max_attempts** (integer) - Optional - Maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - Interval in seconds between polls.

### Response Example
```json
{
  "status": "completed",
  "results": {
    "throughput": "945 Mbits/sec"
  }
}
```
```

--------------------------------

### Get Switch VSX Details

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves Virtual Switching Extension (VSX) configuration and operational state for a switch. Returns an empty VSX object if not configured.

```python
vsx = MonitoringSwitches.get_switch_vsx(conn, serial_number="SWCX001")
```

--------------------------------

### Troubleshooting.tcp_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates a TCP port reachability test from the specified device to a target host/port.

```APIDOC
## Troubleshooting.tcp_test()

### Description
Initiates a TCP port reachability test from the specified device to a target host/port.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - Serial number of the device.
- **destination** (string) - Required - The target host IP address or hostname.
- **port** (integer) - Required - The target port number.
- **max_attempts** (integer) - Optional - Maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - Interval in seconds between polls.

### Response Example
```json
{
  "status": "completed",
  "results": {}
}
```
```

--------------------------------

### Get Health Details for a Specific Site

Source: https://context7.com/aruba/pycentral/llms.txt

Returns full health details for a specific site by its integer site ID. Requires a connection object and the site ID.

```python
site = MonitoringSites.list_site_information(conn, site_id=1001)
# {"siteId": 1001, "siteName": "HQ Campus", "health": "Good", "apCount": 20, ...}
```

--------------------------------

### MonitoringSites.get_all_sites()

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieve all sites with health data. Fetches a complete list of sites including health details, device counts, client counts, and critical alerts, with automatic pagination handling. Simplified site records are returned by default.

```APIDOC
## MonitoringSites.get_all_sites()

### Description
Fetches the complete list of sites with health details (device counts, client counts, critical alerts), handling pagination. Returns simplified site records by default; set `return_raw_response=True` for raw API payloads.

### Parameters
- **conn**: Connection object
- **return_raw_response** (boolean) - Optional - If True, returns the raw API response payload.

### Request Example
```python
from pycentral.new_monitoring import MonitoringSites

sites = MonitoringSites.get_all_sites(conn)
# [{"siteId": 1001, "siteName": "HQ Campus", "health": "Good", "deviceCount": 42, ...}, ...]

raw = MonitoringSites.get_all_sites(conn, return_raw_response=True)
```
```

--------------------------------

### Get AP Memory Utilization Trend

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches memory utilization trend data for a specific AP over a given duration. Requires AP serial number and duration.

```python
mem = MonitoringAPs.get_ap_memory_utilization(
    conn, serial_number="CNAP0001", duration="6h"
)
```

--------------------------------

### Troubleshooting.speedtest_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates an internet speed test from the specified gateway device and polls for download/upload results.

```APIDOC
## Troubleshooting.speedtest_test()

### Description
Initiates an internet speed test from the specified gateway device and polls for download/upload results.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - Serial number of the gateway device.
- **max_attempts** (integer) - Optional - Maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - Interval in seconds between polls.

### Response Example
```json
{
  "status": "completed",
  "results": {
    "downloadMbps": 450,
    "uploadMbps": 220
  }
}
```
```

--------------------------------

### Get AP CPU Utilization Trend

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches CPU utilization trend data for a specific AP over a given duration. Requires AP serial number and duration.

```python
cpu = MonitoringAPs.get_ap_cpu_utilization(
    conn, serial_number="CNAP0001", duration="1h"
)
```

--------------------------------

### Troubleshooting.ping_gateways_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Run a ping test from a gateway. Initiates a ping diagnostic from the specified gateway device to a destination IP address.

```APIDOC
## Troubleshooting.ping_gateways_test()

### Description
Initiates a ping diagnostic from the specified gateway device.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - The serial number of the gateway.
- **destination** (string) - Required - The destination IP address for the ping test.
- **count** (integer) - Optional - The number of ping packets to send.
- **max_attempts** (integer) - Optional - The maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - The interval in seconds between polling attempts.

### Request Example
```python
result = Troubleshooting.ping_gateways_test(
    central_conn=conn,
    serial_number="GW001",
    destination="8.8.4.4",
    count=5,
    max_attempts=10,
    poll_interval=5,
)
```
```

--------------------------------

### List Running Troubleshooting Tasks

Source: https://context7.com/aruba/pycentral/llms.txt

Returns a list of all currently active troubleshooting tasks associated with your account.

```python
tasks = Troubleshooting.list_active_tasks(central_conn=conn)
# {"tasks": [{"taskId": "abc-123", "deviceSerial": "CNAP0001", "type": "ping", "status": "running"}]}}
```

--------------------------------

### Get Switch Interface Details

Source: https://context7.com/aruba/pycentral/llms.txt

Returns interface-level details for a switch, including port speed, status, PoE, VLAN mode, and neighbour information. Supports filtering and sorting.

```python
interfaces = MonitoringSwitches.get_switch_interfaces(
    conn,
    serial_number="SWCX001",
    filter_str="status eq 'Up'",
    sort="name asc",
    limit=50,
)
# {"items": [{"name": "1/1/1", "speed": "1G", "status": "Up", "poeClass": "4"}, ...]}
```

--------------------------------

### List Troubleshooting and Audit Events

Source: https://context7.com/aruba/pycentral/llms.txt

Retrieves historical troubleshooting and network events based on specified filters, including device serial number, start time, and end time.

```python
events = Troubleshooting.list_events(
    central_conn=conn,
    serial_number="CNAP0001",
    start_time=1710000000,
    end_time=1710086400,
)
# {"events": [{"eventType": "connection_failure", "timestamp": 1710003600, ...}]}}
```

--------------------------------

### Troubleshooting.http_test()

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates an HTTP connectivity test from the specified gateway to a target URL and polls for results.

```APIDOC
## Troubleshooting.http_test()

### Description
Initiates an HTTP connectivity test from the specified gateway to a target URL and polls for results.

### Parameters
- **central_conn**: Connection object
- **serial_number** (string) - Required - Serial number of the gateway.
- **url** (string) - Required - The target URL for the HTTP test.
- **max_attempts** (integer) - Optional - Maximum number of attempts to poll for results.
- **poll_interval** (integer) - Optional - Interval in seconds between polls.

### Response Example
```json
{
  "status": "completed",
  "results": {
    "httpStatus": 200,
    "responseTime": 45
  }
}
```
```

--------------------------------

### Get Clients Associated with a Device

Source: https://context7.com/aruba/pycentral/llms.txt

Fetches all clients associated with a specific AP, switch, or gateway using its serial number. Requires a connection object and the device's serial number.

```python
device_clients = Clients.get_clients_associated_device(conn, serial_number="CNAP0001")
```

--------------------------------

### Run iPerf Bandwidth Test

Source: https://context7.com/aruba/pycentral/llms.txt

Initiates an iPerf bandwidth test between a device and an iPerf server and polls for throughput results.

```python
result = Troubleshooting.iperf_test(
    central_conn=conn,
    serial_number="CNAP0001",
    server_ip="10.0.0.50",
    port=5201,
    max_attempts=15,
    poll_interval=5,
)
# {"status": "completed", "results": {"throughput": "945 Mbits/sec"}}
```

--------------------------------

### Retrieve a Single Page of Access Points

Source: https://context7.com/aruba/pycentral/llms.txt

Returns one page of AP records from `GET network-monitoring/v1/aps`. Raises `ParameterError` if `limit > 100` or `next_page < 1`. Supports filtering and pagination.

```python
page = MonitoringAPs.get_aps(
    conn,
    filter_str="status eq 'Up'",
    limit=50,
    next_page=1,
)
# {"items": [...], "total": 120, "next": 2}
```

--------------------------------

### MonitoringSwitches.get_topn_interface_trends()

Source: https://context7.com/aruba/pycentral/llms.txt

Returns the top bandwidth-consuming switch interfaces for a site over a time window.

```APIDOC
## MonitoringSwitches.get_topn_interface_trends()

### Description
Returns the top bandwidth-consuming switch interfaces for a site over a time window.

### Method
GET

### Endpoint
`/network-monitoring/v1/sites/{site_id}/topn-interfaces`

### Parameters
#### Path Parameters
- **site_id** (string) - Required - The ID of the site.
#### Query Parameters
- **duration** (string) - Required - The time window for which to fetch the top interfaces (e.g., '3h', '1d').

### Request Example
```python
topn = MonitoringSwitches.get_topn_interface_trends(
    conn, site_id="site-uuid-1234", duration="3h"
)
```
```