Common Monitoring Use Cases

This page brings the monitoring API categories together through common operational and reporting use cases.

Choose Stored Statistics for Continuous Monitoring

A common design mistake is to poll device real-time endpoints continuously to build a monitoring history. Each request must be processed by the selected device, so this approach consumes device and SD-WAN Manager resources and does not scale across a large fabric.

Use real-time endpoints for an immediate troubleshooting snapshot. For continuous collection, dashboards, reporting, and trend analysis, query the SD-WAN Manager statistics database instead.

Use case	Immediate troubleshooting or current-state endpoint	Recommended scalable endpoint
CPU utilization, uptime, and system status	GET /device/system/status?deviceId={system-ip} Useful response fields: cpu_user, cpu_system, cpu_idle, uptime, uptime-date, lastupdated	POST /statistics/system for stored system measurements over a time range
Interface speed, state, utilization, traffic, drops, and errors	GET /device/interface?deviceId={system-ip} Useful response fields: vdevice-dataKey, if-admin-status, if-oper-status, speed-mbps, uptime-date, lastupdated, rx-octets, tx-octets, rx-packets, tx-packets, rx-drops, tx-drops, rx-errors, tx-errors	POST /statistics/interface for historical records, or POST /statistics/interface/aggregation for grouped and bucketized utilization
Tunnel up/down state across devices	GET /data/device/state/BFDSessions This is a bulk state call, not a device real-time call. Useful response fields: vdevice-host-name, system-ip, state	POST /statistics/approute when historical tunnel state and application-route measurements are required
Tunnel traffic for one device	GET /device/tunnel/statistics?deviceId={system-ip} Useful response fields: vdevice-host-name, system-ip, rx_octets, tx_octets	POST /statistics/approute for historical tunnel traffic, filtering, and trend analysis

Do not turn troubleshooting calls into a polling system

Even when a /device endpoint returns counters, repeatedly polling it to create a time series is not recommended. Use Statistics APIs for stored history or Bulk APIs for batched collection across devices. Review the rate limits and load-management guidance before setting a collection interval.

---

Replace Analytics Aggregation Calls

Some SD-WAN Manager interfaces use unpublished paths under /analytics/api/v4/dataservice/aggregate/. These paths are not part of the 26.1 OpenAPI specification and should not be treated as stable public APIs. The documented monitoring APIs provide the underlying application, site, and circuit aggregation capabilities.

Analytics use case	Documented monitoring API
Applications by traffic utilization	POST /statistics/dpi/aggregation
Sites by availability	POST /statistics/nwa/details with type=site
Circuits by availability	POST /statistics/nwa/details with type=link

There is no first-class circuit object in these APIs. Model a circuit as a link or TLOC identified by device system IP and transport color. When the use case is path quality rather than availability, use POST /statistics/approute/aggregation and group by the applicable local and remote system IPs and colors.

Applications by Traffic Utilization

Aggregate DPI records by application family and sum the observed octets over the last 24 hours. This is the documented alternative to /analytics/api/v4/dataservice/aggregate/applications for a utilization view.

POST/statistics/dpi/aggregationAggregate applications by utilization

Headers

X-XSRF-TOKEN: <X-XSRF-TOKEN>
Authorization: Bearer {{apikey}}
Content-Type: application/json

Request body

{
  "query": {
    "condition": "AND",
    "rules": [
      {
        "value": ["24"],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      }
    ]
  },
  "aggregation": {
    "field": [
      {
        "property": "family",
        "size": 200,
        "sequence": 1
      }
    ],
    "metrics": [
      {
        "property": "octets",
        "type": "sum",
        "order": "desc"
      }
    ]
  }
}

Response - 200 OK

The response groups DPI observations by family and returns the summed octets, with the highest-utilization groups first.

Application names and health

Use /statistics/dpi/fields and /statistics/dpi/query/fields to check whether the target release exposes a more specific application grouping. For application health or QoE across sites, use GET /statistics/perfmon/applications/sites/health instead.

Sites by Availability

Filter Network Availability records to site, group them by site ID, and sum downtime over the last 24 hours. This replaces /analytics/api/v4/dataservice/aggregate/sites when the required result is site availability.

POST/statistics/nwa/detailsAggregate sites by availability

Headers

X-XSRF-TOKEN: <X-XSRF-TOKEN>
Authorization: Bearer {{apikey}}
Content-Type: application/json

Request body

{
  "query": {
    "condition": "AND",
    "rules": [
      {
        "value": ["24"],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      },
      {
        "value": ["site"],
        "field": "type",
        "type": "string",
        "operator": "in"
      }
    ]
  },
  "aggregation": {
    "field": [
      {
        "property": "site_id",
        "sequence": 1,
        "size": 100
      }
    ],
    "metrics": [
      {
        "property": "down_time",
        "type": "sum",
        "order": "desc"
      }
    ]
  }
}

Response - 200 OK

The response returns site-level Network Availability records, including availability and health information. For a ready-made health summary, use GET /statistics/sitehealth/common?last_n_hours=24&includeDetails=true.

Circuits by Availability

Filter Network Availability records to link, then group them by device system IP and transport color. This is the closest documented availability replacement for /analytics/api/v4/dataservice/aggregate/circuits.

POST/statistics/nwa/detailsAggregate circuits by availability

Headers

X-XSRF-TOKEN: <X-XSRF-TOKEN>
Authorization: Bearer {{apikey}}
Content-Type: application/json

Request body

{
  "query": {
    "condition": "AND",
    "rules": [
      {
        "value": ["24"],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      },
      {
        "value": ["link"],
        "field": "type",
        "type": "string",
        "operator": "in"
      }
    ]
  },
  "aggregation": {
    "field": [
      {
        "property": "system_ip",
        "sequence": 1,
        "size": 100
      },
      {
        "property": "color",
        "sequence": 2,
        "size": 100
      }
    ],
    "metrics": [
      {
        "property": "down_time",
        "type": "sum",
        "order": "desc"
      }
    ]
  }
}

Response - 200 OK

The response returns link-level Network Availability records for each system-IP and color combination.

Circuit quality uses AppRoute statistics

For latency, jitter, and loss, use POST /statistics/approute/aggregation. Group by the relevant combination of local_system_ip, local_color, remote_system_ip, and remote_color, then average latency, jitter, and loss_percentage.

---

Practice with Bruno

After completing authentication, run these requests from the Monitoring APIs folder:

1. 07 - Aggregate Applications by Utilization groups DPI traffic by application family.
2. 08 - Aggregate Sites by Availability summarizes downtime by site.
3. 09 - Aggregate Circuits by Availability summarizes downtime by device and transport color.

The site and circuit examples use a 24-hour window. The application example uses 1,000 hours because the demo environment has sparse DPI history; reduce that window for an active production network. Discover supported fields on the target release and review Monitoring API Best Practices before increasing the window or request frequency.

Automate with Python

The standalone Python examples implement all seven operational and aggregation cases discussed in this guide. See Python Monitoring Examples for commands, output options, and the process for registering another use case.