Monitoring API Best Practices

Monitoring integrations must balance freshness and scale against SD-WAN Manager and device resource utilization.

Use Real-Time APIs for Troubleshooting Only

Use Statistics APIs for ongoing historical analysis and Bulk APIs for collection across multiple devices.

Rate Limits

Cisco introduced API rate limits in SD-WAN Manager 20.6. The documented limits and the more conservative real-time operating recommendation are:

API traffic	Limit or recommendation
Real-time monitoring	Stay below 50 requests per second and use only for targeted troubleshooting
Statistics bulk — `/dataservice/data/device/statistics/`	48 requests per minute and no more than two concurrent requests
All other APIs	100 requests per second

The rate limit is a ceiling, not a performance target. A response with status 429 Too Many Requests means the client exceeded an enforced limit and must reduce its request rate.

See Cisco’s rate-limit and pagination guidance for the current platform limits.

Increase Load Gradually

Start with a low request count and frequency. Increase one dimension at a time while monitoring every SD-WAN Manager node for:

CPU and memory utilization
API latency and timeout rate
HTTP 429 and 5xx responses
Statistics-query and bulk-export duration
Device reachability and real-time response latency

Stop increasing the workload if it causes resource pressure, slower responses, timeouts, or other performance degradation.

Query Efficiently

Discover valid fields for each statistics or bulk data type before hard-coding filters and parsers.
Select only the fields required by the application.
Keep statistics time windows narrow while developing a query, then widen them after validating the result size and Manager load.
Use aggregation on SD-WAN Manager when the application needs a summary rather than every raw record.
Use /doccount before exporting a large historical range.
Follow startId or scrollId cursors until all batches are retrieved; do not restart the first page repeatedly.
Limit retries with exponential backoff and jitter instead of retrying immediately in a tight loop.

Handle Bulk Scale Deliberately

Statistics bulk APIs can retrieve millions of records from the internal SD-WAN Manager statistics database. Large exports should:

Estimate volume with /doccount.
Bound the start and end times.
Use a controlled page size.
Respect the two-request concurrency limit.
Persist the current cursor so collection can resume safely.
Stream or incrementally process records instead of keeping the complete export in memory.

Design for Failure

Expect real-time requests to fail when a device is unreachable even if SD-WAN Manager is healthy.
Treat empty data separately from transport, authorization, and rate-limit errors.
Record the query window, data type, cursor, HTTP status, and Manager node with each failure.
Do not assume every statistics type uses the same collection or refresh interval.
Validate endpoints, fields, and limits against the deployed SD-WAN Manager release.

HTTP Response Codes

Code	Meaning
`200`	Request succeeded
`400`	Invalid parameter or query payload
`401`	Authentication is missing or invalid
`403`	The authenticated user lacks the required read role
`404`	Endpoint, device, or data type was not found
`429`	The request exceeded an API rate limit
`500`	SD-WAN Manager or device-side processing failed

These recommendations and examples target Cisco Catalyst SD-WAN Manager 26.1. Verify compatibility and configured limits on the deployed release and cluster.

Continue to Common Monitoring Use Cases to apply these guidelines to operational and Analytics aggregation workflows.