Skip to content
Catalyst SD-WAN APIs

Statistics APIs

The SD-WAN Manager NMS statistics database periodically collects statistics from WAN Edge routers, beginning when each router joins the overlay. Statistics APIs query that stored history.

Unlike real-time calls, statistics queries analyze a time window without querying the device at that moment. The query language supports simple record selection and aggregation.

Discover Statistics Types and Fields

Section titled “Discover Statistics Types and Fields”
Method and endpoint Purpose
GET /statistics List the statistics types available on SD-WAN Manager
GET /statistics/{type}/fields List stored fields and their data types
GET /statistics/{type}/query/fields List fields available to query rules
POST /statistics/{type} Run a simple query and return matching raw records
POST /statistics/{type}/aggregation Group, bucketize, and calculate metrics over matching records
POST /statistics/{type}/doccount Count records matching a query

Examples of {type} include interface, approute, bfd, device, qos, system, and system/stats. The 26.1 specification defines many additional domain-specific types.

Query Building Blocks

Section titled “Query Building Blocks”
Element Purpose
query.condition Combines rules, normally with AND or OR
query.rules Filters by time, device, interface, color, or another queryable field
fields Selects fields returned by a simple query
sort Orders results by one or more fields
aggregation.field Groups records by a property
aggregation.metrics Calculates values such as sum, count, avg, min, or max
aggregation.histogram Bucketizes time-series data into supported intervals

Simple Query

Section titled “Simple Query”

A simple query selects fields, defines a time period and other filters, and specifies the result order.

Aggregated Query

Section titled “Aggregated Query”

An aggregated query filters stored records, groups or bucketizes them, and calculates metrics over each group.

Simple Interface Statistics Query

Section titled “Simple Interface Statistics Query”

This example retrieves selected interface statistics for one device over the last six hours and sorts the newest records first.

POST/statistics/interface?pageSize=100Run a simple interface statistics query
Headers
X-XSRF-TOKEN: <X-XSRF-TOKEN>
Authorization: Bearer {{apikey}}
Content-Type: application/json

Request body

{
  "query": {
    "condition": "AND",
    "rules": [
      {
        "value": ["6"],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      },
      {
        "value": ["10.0.0.20"],
        "field": "vdevice_name",
        "type": "string",
        "operator": "in"
      }
    ]
  },
  "fields": [
    "entry_time",
    "vdevice_name",
    "host_name",
    "interface",
    "rx_kbps",
    "tx_kbps"
  ],
  "sort": [
    {
      "field": "entry_time",
      "type": "date",
      "order": "desc"
    }
  ]
}

Response - 200 OK

An array of matching interface-statistics records, limited here to 100 records by pageSize.

Aggregate Interface Throughput

Section titled “Aggregate Interface Throughput”

This example calculates average receive and transmit throughput per interface in 30-minute buckets.

POST/statistics/interface/aggregationAggregate interface throughput
Headers
X-XSRF-TOKEN: <X-XSRF-TOKEN>
Authorization: Bearer {{apikey}}
Content-Type: application/json

Request body

{
  "query": {
    "condition": "AND",
    "rules": [
      {
        "value": ["6"],
        "field": "entry_time",
        "type": "date",
        "operator": "last_n_hours"
      },
      {
        "value": ["10.0.0.20"],
        "field": "vdevice_name",
        "type": "string",
        "operator": "in"
      }
    ]
  },
  "sort": [
    {
      "field": "entry_time",
      "type": "date",
      "order": "asc"
    }
  ],
  "aggregation": {
    "field": [
      {
        "property": "interface",
        "sequence": 1
      }
    ],
    "histogram": {
      "property": "entry_time",
      "type": "minute",
      "interval": 30,
      "order": "asc"
    },
    "metrics": [
      {
        "property": "rx_kbps",
        "type": "avg"
      },
      {
        "property": "tx_kbps",
        "type": "avg"
      }
    ]
  }
}

Response - 200 OK

An array of aggregated records containing the interface, time bucket, record count, and calculated rx_kbps and tx_kbps values.

Filter an explicit time range and interface set
{
  "condition": "AND",
  "rules": [
    {
      "field": "entry_time",
      "type": "date",
      "operator": "between",
      "value": ["2026-08-12T08:00:00", "2026-08-12T10:00:00"]
    },
    {
      "field": "interface",
      "type": "string",
      "operator": "in",
      "value": ["GigabitEthernet1", "GigabitEthernet2"]
    }
  ]
}

Practice with Bruno

Section titled “Practice with Bruno”

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

  1. 03 - Simple Interface Statistics Query retrieves selected historical fields from the Manager statistics database.
  2. 04 - Aggregate Interface Statistics Query calculates average throughput per interface in 30-minute buckets.

Try It with Python

Section titled “Try It with Python”
Terminal window
uv run -m monitoring.run_cases --insecure applications --hours 24
uv run -m monitoring.run_cases --insecure sites --hours 24
uv run -m monitoring.run_cases --insecure circuits --hours 24

See Python Monitoring Examples for output options and the extension pattern.

Next Steps

Section titled “Next Steps”