Skip to main content

Inventory Device Diags

The Inventory Device Diagnostics API enables you to configure and manage network diagnostic tests on managed devices. These endpoints allow you to schedule diagnostic operations like bandwidth tests, connectivity checks, and network troubleshooting directly on customer premises equipment (CPE) from your control platform.

Base URL: https://control.zequenze.com/api/v1

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Device Diagnostics API provides comprehensive network diagnostic capabilities for managed devices in your inventory. This API category allows you to remotely execute various diagnostic tests on customer premises equipment (CPE) to troubleshoot connectivity issues, measure network performance, and gather detailed network information.

Key Features:

  • Execute multiple diagnostic operations: HTTP download/upload tests, ICMP ping, UDP echo tests, traceroute, DNS lookups, and WiFi neighbor scans
  • Configure test parameters like packet count, size, timeout values, and connection settings
  • Target specific network interfaces on devices
  • Retrieve diagnostic results and device status information

Common Use Cases:

  • Network Troubleshooting: When customers report connectivity issues, quickly run ping, traceroute, or DNS lookup tests to identify problems
  • Performance Monitoring: Schedule regular bandwidth tests using download/upload operations to monitor service quality
  • WiFi Environment Analysis: Use WiFi neighbor diagnostics to analyze interference and optimize wireless settings
  • Service Validation: Verify network connectivity and performance after device installations or configuration changes

The diagnostic operations are executed directly on the target devices, providing real-time network insights from the customer's actual network environment.

Endpoints

GET /inventory_device_diags/

Description: Retrieves a list of configured diagnostic operations for devices in your inventory. This endpoint allows you to view existing diagnostic configurations and optionally update device status information before returning results. Use this to monitor scheduled diagnostics or review diagnostic configurations across your managed devices.

Use Cases:

  • Review all configured diagnostic tests across your device inventory
  • Check the status of devices before planning new diagnostic operations
  • Audit diagnostic configurations for compliance or troubleshooting purposes
  • Monitor ongoing diagnostic operations and their parameters

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_diags/?id=12345&update_status=true

Parameters:

Parameter Type In Required Description
id string query No Filter results to show diagnostics for a specific device by its ID
update_status boolean query No When set to true, uses configured helpers to refresh device status before returning diagnostic information

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_device_diags/?update_status=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

[
  {
    "id": 12345,
    "operation": "download",
    "target": "http://speedtest.example.com/download/test.bin",
    "upload_size": null,
    "count": null,
    "size": null,
    "timeout": null,
    "dns_server": null,
    "max_hops": null,
    "interface": "eth0",
    "number_of_connections": 4
  },
  {
    "id": 12346,
    "operation": "ipping",
    "target": "8.8.8.8",
    "upload_size": null,
    "count": 10,
    "size": 64,
    "timeout": 3,
    "dns_server": null,
    "max_hops": null,
    "interface": "wan0",
    "number_of_connections": null
  },
  {
    "id": 12347,
    "operation": "wifi.neighbor",
    "target": "channel_scan",
    "upload_size": null,
    "count": null,
    "size": null,
    "timeout": null,
    "dns_server": null,
    "max_hops": null,
    "interface": "wlan0",
    "number_of_connections": null
  }
]

Response Codes:

Status Description
200 Success - Returns array of diagnostic configurations
401 Unauthorized - Invalid or missing API token
500 Internal Server Error - Problem retrieving diagnostic data

POST /inventory_device_diags/

Description: Creates a new diagnostic operation configuration for a device. This endpoint allows you to schedule various network diagnostic tests including bandwidth measurements, connectivity tests, and network analysis operations. The diagnostic will be queued for execution on the target device according to the specified parameters.

Use Cases:

  • Schedule bandwidth tests to measure download/upload speeds for service validation
  • Configure ping tests to monitor connectivity to specific hosts or services
  • Set up traceroute diagnostics to identify network path issues
  • Create DNS lookup tests to troubleshoot name resolution problems
  • Schedule WiFi neighbor scans to analyze wireless environment

Full URL Example:

https://control.zequenze.com/api/v1/inventory_device_diags/

Request Body Parameters:

The request body should contain a JSON object with the diagnostic configuration:

Parameter Type Required Description
id integer Yes ID of the target device where the diagnostic will be executed
operation string Yes Type of diagnostic operation. Allowed values: download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor
target string Yes Target for the operation - URL for download/upload, IP for ping/traceroute, hostname for DNS lookup, or parameter for WiFi diagnostics
upload_size string No Size in MB for upload operations (e.g., "10")
count integer No Number of packets for ping (default: 5) or DNS lookup repetitions (default: 1)
size integer No Packet size in bytes for ping operations (default: 64)
timeout integer No Response timeout in seconds for ping and DNS operations (default: 1)
dns_server string No Specific DNS server IP for DNS lookup operations
max_hops integer No Maximum hops for traceroute operations (default: 30)
interface string No Network interface name to use for the operation
number_of_connections integer No Number of concurrent connections for download/upload tests

cURL Examples:

Bandwidth Download Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12345,
    "operation": "download",
    "target": "http://speedtest.example.com/download/100MB.bin",
    "interface": "eth0",
    "number_of_connections": 4
  }'

Ping Connectivity Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12346,
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 20,
    "size": 1024,
    "timeout": 3,
    "interface": "wan0"
  }'

DNS Lookup Test:

curl -X POST "https://control.zequenze.com/api/v1/inventory_device_diags/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 12347,
    "operation": "dnslookup",
    "target": "www.example.com",
    "count": 3,
    "timeout": 5,
    "dns_server": "1.1.1.1"
  }'

Example Response:

{
  "id": 12348,
  "operation": "download",
  "target": "http://speedtest.example.com/download/100MB.bin",
  "upload_size": null,
  "count": null,
  "size": null,
  "timeout": null,
  "dns_server": null,
  "max_hops": null,
  "interface": "eth0",
  "number_of_connections": 4
}

Response Codes:

Status Description
201 Created - Diagnostic operation successfully configured
400 Bad Request - Invalid parameters or missing required fields
401 Unauthorized - Invalid or missing API token
404 Not Found - Specified device ID does not exist
500 Internal Server Error - Problem creating diagnostic configuration

Common Use Cases

Use Case 1: Customer Speed Complaint Investigation

When a customer reports slow internet speeds, create download and upload diagnostic tests to measure actual throughput from their device to your test servers and identify if the issue is with download, upload, or both directions.

Use Case 2: Connectivity Troubleshooting

If a customer experiences intermittent connectivity issues, schedule ping tests to critical infrastructure (DNS servers, gateways, service endpoints) with increased packet counts and varying sizes to identify packet loss or latency patterns.

Use Case 3: WiFi Performance Optimization

Before and after WiFi configuration changes, use WiFi neighbor diagnostics to scan for interference sources and optimal channel selection, helping to optimize wireless performance in crowded RF environments.

Use Case 4: Service Installation Validation

After installing new equipment or services, run a comprehensive diagnostic suite including ping tests to verify gateway connectivity, DNS lookups to confirm name resolution, and bandwidth tests to validate service delivery speeds.

Use Case 5: Proactive Network Monitoring

Schedule regular diagnostic operations across your device inventory to proactively identify network degradation, plan capacity upgrades, and maintain service quality before customers experience issues.

Best Practices

Operation Selection:

  • Use ipping for basic connectivity verification and latency measurement
  • Use download/upload for bandwidth validation and service speed verification
  • Use traceroute when you need to identify where in the network path issues occur
  • Use wifi.neighbor for wireless environment analysis and channel optimization

Parameter Configuration:

  • For ping operations, use count values of 10-20 for reliable statistics while avoiding network flooding
  • Set appropriate timeouts based on expected network conditions (3-5 seconds for typical broadband)
  • When testing bandwidth, use multiple connections (2-8) to better utilize available capacity
  • Specify network interfaces when devices have multiple connection paths

Error Handling:

  • Always validate device IDs exist before creating diagnostic operations
  • Handle 404 responses gracefully when devices are offline or unreachable
  • Implement retry logic for temporary network issues during diagnostic execution
  • Monitor diagnostic results and alert on repeated failures indicating persistent issues

Performance Considerations:

  • Avoid scheduling too many simultaneous diagnostics on the same device
  • Space out bandwidth-intensive tests (download/upload) to prevent network congestion
  • Use the update_status parameter judiciously as it adds processing time to GET requests
  • Consider rate limiting diagnostic creation to prevent overwhelming device resources
Back to top