Skip to main content

Inventory Device Diags

Endpoints Summary

Method Path Swagger POST /inventory_device_diags/ Swagger ↗ GET /inventory_device_diags/ Swagger ↗

The Inventory Device Diagnostics API enables you to configurecreate and managemonitor network diagnostic testsoperations onfor manageddevices devices.in your inventory. These endpoints allow you to schedule diagnosticvarious operationsnetwork tests like bandwidthping, traceroute, speed tests, connectivityand checks,WiFi diagnostics, then retrieve results and status information for troubleshooting and network troubleshootingperformance directly on customer premises equipment (CPE) from your control platform.analysis.

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.devices. This API category allows younetwork administrators and developers to remotelyprogrammatically execute various diagnostic testsoperations on customer premises equipment (CPE) to troubleshootincluding connectivity issues,tests, measureperformance measurements, and network performance,discovery and gather detailed network information.tools.

Key Features:

  • Execute multipleMultiple diagnosticDiagnostic operations:Types: Support for HTTP download/upload tests, ICMP ping, UDP echo tests,echo, traceroute, DNS lookups, and WiFi neighbor scansdiscovery
  • Configure testFlexible Configuration: Customizable parameters likefor packet count, size, timeout values, connection counts, and connection settingsmore
  • Real-time Monitoring: Track diagnostic operation status and retrieve results as they become available
Interface-specific Testing: Target specific network interfaces onfor devicesprecise Retrieve diagnostic results and device status informationdiagnostics

Common Use Cases:

  • Automated Networknetwork Troubleshooting:health Whenmonitoring customersand reportalerting
Troubleshooting connectivity issues,issues quickly run ping, traceroute, or DNS lookup tests to identify problemsremotely Performance Monitoring:benchmarking Scheduleand regularcapacity bandwidth tests using download/upload operations to monitor service qualityplanning WiFi Environmentnetwork Analysis: Use WiFi neighbor diagnostics to analyze interferenceanalysis and optimize wireless settingsoptimization Compliance Servicereporting Validation:for VerifySLA network connectivity and performance after device installations or configuration changesmonitoring

The diagnostic operations are executed directlyasynchronously on the target devices, providingallowing real-timeyou networkto insightsschedule frommultiple tests and check their progress using the customer'slist actual network environment.endpoint.

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 specific device. This endpoint allows you to scheduleschedules various networktypes diagnostic tests including bandwidth measurements, connectivity tests, andof network analysisdiagnostics operations. The diagnosticthat will be queued for executionexecuted on the target devicedevice, accordingincluding toconnectivity thetests, specifiedperformance parameters.measurements, and network discovery operations.

    Use Cases:

    • Schedule bandwidthautomated testsnetwork tohealth measurechecks
    download/uploadPerform speedson-demand troubleshooting for service validation Configure ping tests to monitor connectivity to specific hosts or services Set up traceroute diagnostics to identify network path issues CreateExecute DNSperformance lookupbenchmarks testsfor tobandwidth troubleshoot name resolution problemstesting ScheduleConduct WiFi site surveys and neighbor scans to analyze wireless environmentanalysis

    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 wherefrom theyour diagnostic will be executedinventory
    operation string Yes Type of diagnostic operation. Allowed values:Options: download, upload, ipping, udpecho, traceroute, dnslookup, wifi.neighbor
    target string Yes Target for the operation - URL for (download/upload,upload), IP foraddress (ping/traceroute,traceroute), hostname for (DNS lookup,lookup), or parameter for (WiFi diagnosticsdiagnostics)
    upload_size string No SizeFile size in MB for upload operations (e.g., "10"100")
    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 ping/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 concurrentConcurrent connections for download/upload tests

    cURL Examples:Example - Ping 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": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2
  }'

    BandwidthcURL DownloadExample - Speed 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",
    "number_of_connections": 4,
    "interface": "eth0",
    "number_of_connections": 4
  }'

    PingExample Connectivity Test:Response:

    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,12345,
  "operation": "ipping",
  "target": "8.8.8.8",
  "count": 20,10,
  "size": 1024,64,
  "timeout": 3,2,
  "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"eth0",
  "upload_size": null,
  "count": null,
  "size": null,
  "timeout": null,
  "dns_server": null,
  "max_hops": null,
  "interface": "eth0",
  "number_of_connections": 4null
}

    Response Codes:

    Status Description
    201 Created - Diagnostic operation scheduled successfully configured
    400 Bad Request - Invalid parameters or missing required fields
    401 Unauthorized - Invalid or missing API token
    404 Not Found - SpecifiedDevice ID not found in inventory

    GET /inventory_device_diags/

    Description: Retrieves a list of diagnostic operations, either all operations or filtered by specific criteria. This endpoint allows you to monitor the status of scheduled diagnostics and retrieve results from completed operations.

    Use Cases:

      Monitor progress of scheduled diagnostic operations Retrieve diagnostic results for analysis and reporting Check the status of specific diagnostic transactions Update device connectivity status before retrieving diagnostics

      Full URL Example:

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

      Parameters:

      Parameter Type In Required Description id string query No ID doesof nota existspecific scheduled diagnostic transaction to retrieve 500update_status Internalboolean Serverquery ErrorNo Whether to refresh device status using configured helpers before returning data

      cURL Example - ProblemList creatingAll Diagnostics:

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

      cURL Example - Get Specific Diagnostic:

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

      Example Response:

      [
  {
    "id": 12345,
    "operation": "ipping",
    "target": "8.8.8.8",
    "count": 10,
    "size": 64,
    "timeout": 2,
    "interface": "eth0",
    "upload_size": null,
    "dns_server": null,
    "max_hops": null,
    "number_of_connections": null
  },
  {
    "id": 12346,
    "operation": "download",
    "target": "http://speedtest.example.com/100MB.bin",
    "count": null,
    "size": null,
    "timeout": null,
    "interface": "wlan0",
    "upload_size": null,
    "dns_server": null,
    "max_hops": null,
    "number_of_connections": 4
  },
  {
    "id": 12347,
    "operation": "traceroute",
    "target": "google.com",
    "count": null,
    "size": null,
    "timeout": null,
    "interface": null,
    "upload_size": null,
    "dns_server": null,
    "max_hops": 20,
    "number_of_connections": null
  }
]

      Response Codes:

      Status Description 200 Success - Returns list of diagnostic configurationoperations 401 Unauthorized - Invalid or missing API token 404 Not Found - Specific diagnostic ID not found (when using id parameter)

      Common Use Cases

      Use Case 1: CustomerAutomated SpeedNetwork ComplaintHealth InvestigationMonitoring

      WhenSchedule aregular customerping reportsand slowconnectivity internettests speeds,for critical devices to monitor network health. Use the POST endpoint to create downloadrecurring diagnostic jobs and uploadthe diagnosticGET testsendpoint to measureretrieve actualresults throughputfor fromdashboard their device to your test servers and identify if the issue is with download, upload,displays or bothalerting directions.systems.

      Use Case 2: ConnectivityBandwidth TroubleshootingPerformance Testing

      IfConduct aperiodic customer experiences intermittent connectivity issues, schedule pingspeed tests tousing critical infrastructure (DNS servers, gateways, service endpoints) with increased packet countsdownload and varyingupload sizesoperations to ensure devices meet SLA requirements. Configure multiple connections to test maximum throughput capabilities and identify packetperformance loss or latency patterns.degradation.

      Use Case 3: Troubleshooting Connectivity Issues

      When users report network problems, use traceroute and DNS lookup diagnostics to identify routing issues or DNS resolution problems. The interface parameter allows testing specific network paths.

      Use Case 4: WiFi PerformanceSite Survey and Optimization

      Before and after WiFi configuration changes, useExecute WiFi neighbor diagnostics to scananalyze wireless environments, identify interference sources, and optimize channel assignments for interference sources and optimal channel selection, helping to optimize wirelessbetter performance in crowdeddense RFdeployment 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.scenarios.

      Use Case 5: ProactiveCompliance Networkand MonitoringSLA Reporting

      ScheduleRegularly regularschedule comprehensive diagnostic operationssuites acrossand youruse devicethe inventoryresults tofor proactivelycompliance identifyreporting, SLA verification, and network degradation,performance plandocumentation capacityrequired upgrades,by andregulatory maintainor servicecontractual quality before customers experience issues.obligations.

      Best Practices

      Operation Selection:

      • Use ippingBatch forOperations: basicWhen connectivitytesting verificationmultiple devices, stagger diagnostic operations to avoid network congestion and latencyensure measurementaccurate results
      • Parameter Optimization: Use download/uploadappropriate fortimeout bandwidth validationvalues and servicepacket 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 timeoutscounts based on expected network conditions (3-5- secondslonger timeouts for typicalsatellite broadband)links, higher packet counts for statistical accuracy When testingInterface bandwidth,Selection: use multiple connections (2-8) to better utilize available capacity Specify networktarget interfaces when devices have multiple connectionnetwork connections to test specific paths (e.g., cellular vs. WiFi)

        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 temporaryfailed diagnostics, as network issuesconditions duringor device availability may cause temporary failures Rate Limiting: Respect API rate limits and device processing capabilities by spacing diagnostic executionrequests appropriately Monitor diagnosticResult resultsPolling: 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 addsmay processingimpact performance - only use when real-time tostatus GETupdates requestsare required Consider rateSecurity limitingConsiderations: Ensure diagnostic creationtargets (URLs, IPs) are from trusted sources to prevent overwhelmingdevices devicefrom resourcesaccessing malicious endpoints
            Back to top