Inventory Metric

The Inventory Metric API provides endpoints for retrieving and monitoring various metrics related to your inventory items. These endpoints allow you to access performance data, usage statistics, and operational metrics for devices and resources in your inventory system. Perfect for building dashboards, monitoring systems, and generating reports.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Metric API category enables you to access comprehensive metrics and analytical data about your inventory items. These endpoints are designed to help you monitor performance, track usage patterns, analyze trends, and generate insights about your inventory resources.

Key Features:

Retrieve metrics for all inventory items with filtering capabilities
Access detailed metric data for specific items
Filter results by metric names to focus on specific KPIs
Paginate through large datasets efficiently

Common Metric Types:

CPU utilization and performance metrics
Memory usage statistics
Network throughput and connectivity data
Storage capacity and usage
Uptime and availability metrics
Error rates and system health indicators

These endpoints work together to provide a complete view of your inventory performance - use the list endpoint to get an overview and identify items of interest, then drill down with the detail endpoint for comprehensive metric analysis.

Endpoints

GET /inventory_metric/

Description: Retrieves a paginated list of all inventory metrics in your system. This endpoint is essential for getting an overview of metric data across your entire inventory, with powerful filtering capabilities to narrow down results by metric name.

Use Cases:

Building monitoring dashboards that display multiple inventory metrics
Generating reports on system performance across all devices
Identifying specific metrics by name for focused analysis
Implementing automated alerting systems based on metric thresholds

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric/?name=cpu_usage&limit=50&offset=0

Parameters:

Parameter	Type	In	Required	Description
name	string	query	No	Filter results by the metric's name field. Useful for finding specific metrics like "cpu_usage", "memory_utilization", or "network_throughput"
limit	integer	query	No	Number of results to return per page (default: 20, max: 100). Use for pagination control
offset	integer	query	No	The initial index from which to return results. Use with limit for pagination

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_metric/?name=cpu_usage&limit=25&offset=0" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 147,
  "next": "https://control.zequenze.com/api/v1/inventory_metric/?limit=25&offset=25",
  "previous": null,
  "results": [
    {
      "id": 1,
      "name": "cpu_usage",
      "device_id": 42,
      "device_name": "web-server-01",
      "metric_type": "performance",
      "value": 78.5,
      "unit": "percent",
      "timestamp": "2024-01-15T10:30:00Z",
      "status": "normal",
      "threshold_warning": 80.0,
      "threshold_critical": 95.0
    },
    {
      "id": 2,
      "name": "memory_utilization",
      "device_id": 42,
      "device_name": "web-server-01",
      "metric_type": "performance",
      "value": 6.2,
      "unit": "GB",
      "timestamp": "2024-01-15T10:30:00Z",
      "status": "normal",
      "threshold_warning": 7.0,
      "threshold_critical": 7.8
    },
    {
      "id": 3,
      "name": "network_throughput",
      "device_id": 43,
      "device_name": "database-server-01",
      "metric_type": "network",
      "value": 125.7,
      "unit": "Mbps",
      "timestamp": "2024-01-15T10:29:45Z",
      "status": "normal",
      "threshold_warning": 800.0,
      "threshold_critical": 950.0
    }
  ]
}

Response Codes:

Status	Description
200	Success - Returns the paginated list of inventory metrics
401	Unauthorized - Invalid or missing Bearer token
400	Bad Request - Invalid query parameters

GET /inventory_metric/{id}/

Description: Retrieves detailed information about a specific inventory metric by its unique ID. This endpoint provides comprehensive metric data including historical values, configuration details, and related device information.

Use Cases:

Displaying detailed metric information in monitoring interfaces
Retrieving specific metric data for analysis and reporting
Getting current values and thresholds for alerting systems
Accessing historical trend data for a particular metric

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric/1/?name=cpu_usage

Parameters:

Parameter	Type	In	Required	Description
id	integer	path	Yes	The unique identifier of the inventory metric to retrieve
name	string	query	No	Additional filter by metric name for validation or cross-referencing

cURL Example:

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

Example Response:

{
  "id": 1,
  "name": "cpu_usage",
  "device_id": 42,
  "device_name": "web-server-01",
  "device_type": "server",
  "organization": "Production",
  "metric_type": "performance",
  "description": "CPU utilization percentage for web server",
  "current_value": 78.5,
  "unit": "percent",
  "last_updated": "2024-01-15T10:30:00Z",
  "status": "normal",
  "threshold_warning": 80.0,
  "threshold_critical": 95.0,
  "collection_interval": 60,
  "retention_days": 90,
  "historical_data": [
    {
      "timestamp": "2024-01-15T10:29:00Z",
      "value": 76.2
    },
    {
      "timestamp": "2024-01-15T10:28:00Z",
      "value": 74.8
    },
    {
      "timestamp": "2024-01-15T10:27:00Z",
      "value": 79.1
    }
  ],
  "alerts": [
    {
      "id": 101,
      "type": "warning",
      "triggered_at": "2024-01-15T09:45:00Z",
      "message": "CPU usage approaching warning threshold"
    }
  ],
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Response Codes:

Status	Description
200	Success - Returns the detailed metric information
401	Unauthorized - Invalid or missing Bearer token
404	Not Found - Metric with specified ID does not exist
403	Forbidden - Access denied to this metric

Common Use Cases

Use Case 1: Building a Real-time Monitoring Dashboard

Combine both endpoints to create a comprehensive monitoring dashboard. Use the list endpoint to get an overview of all metrics, then drill down into specific metrics using the detail endpoint for charts and detailed analysis.

Use Case 2: Automated Performance Alerting

Regularly poll the list endpoint filtered by specific metric names (like cpu_usage or memory_utilization) to check current values against thresholds and trigger alerts when necessary.

Use Case 3: Historical Performance Analysis

Use the detail endpoint to access historical data for specific metrics, enabling trend analysis and capacity planning based on past performance patterns.

Use Case 4: Custom Reporting and Analytics

Filter metrics by name and combine data from multiple devices to generate custom reports on system performance, resource utilization, and operational efficiency.

Use Case 5: Inventory Health Assessment

Systematically retrieve metrics across your entire inventory to assess overall system health and identify devices or resources that may need attention.

Best Practices

Use Pagination Effectively: For large inventories, always use the limit parameter to control response size and implement proper pagination using the offset parameter
Filter by Metric Name: When you need specific types of metrics, always use the name parameter to reduce response size and improve performance
Cache Responses: Implement caching for metric data that doesn't change frequently to reduce API calls and improve application performance
Handle Rate Limits: Implement exponential backoff and respect any rate limiting to ensure reliable access to the API
Monitor Response Times: For real-time dashboards, consider the refresh frequency needed versus API performance to provide optimal user experience
Error Handling: Always implement proper error handling for 404 responses when accessing specific metrics, as devices may be removed or metrics may be discontinued
Batch Processing: When analyzing multiple metrics, consider batching requests and processing them efficiently rather than making individual calls for each metric