Skip to main content

Inventory Metric Log

The Inventory Metric Log API provides access to time-series metric data collected from devices in your inventory. These endpoints allow you to query and retrieve historical metrics, measurements, and sensor data with flexible filtering options. Use these endpoints to build dashboards, generate reports, or analyze device performance over time.

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

Authentication: All endpoints require a Bearer token:

Authorization: Bearer <your-api-token>

Overview

The Inventory Metric Log API is designed for accessing and analyzing time-series data collected from various devices in your infrastructure. This API category focuses on retrieving metric logs that contain measurements, sensor readings, and other quantitative data points captured over time.

Key Concepts:

  • Metrics: Quantitative measurements collected from devices (CPU usage, temperature, bandwidth, etc.)
  • Parameters: The specific types of measurements being tracked (variable names, display names, units)
  • Time-series Data: All metrics are timestamped and can be filtered by date ranges
  • Device Association: Every metric log is linked to a specific device in your inventory

Common Use Cases:

  • Building monitoring dashboards with real-time and historical data
  • Generating performance reports for specific devices or time periods
  • Analyzing trends and patterns in device metrics
  • Troubleshooting issues by examining metric history
  • Creating alerts based on metric thresholds

The API supports flexible filtering by device, metric type, parameter names, and time ranges, making it easy to retrieve exactly the data you need for your specific use case.

Endpoints

GET /inventory_metric_log/

Description: Retrieves a paginated list of inventory metric logs with comprehensive filtering options. This endpoint is ideal for fetching multiple metric records across different devices, time periods, and metric types. Use it to build dashboards, generate reports, or perform bulk data analysis.

Use Cases:

  • Fetch all temperature readings from a specific device over the last 24 hours
  • Retrieve CPU metrics from multiple servers within a date range
  • Build real-time monitoring dashboards showing current and historical data
  • Export metric data for external analysis or reporting tools

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric_log/?device__name=server-01&metric_name=cpu_usage&datetime__gte=2024-01-15T00:00:00Z&limit=100

Parameters:

Parameter Type In Required Description
datetime__gte string query No Filter records from this datetime onwards. Accepts ISO format: 2000-01-01, 2000-01-01 00:01:00, or 2000-01-01 00:01:00+00:00
datetime__lte string query No Filter records up to this datetime. Accepts ISO format: 2000-01-01, 2000-01-01 00:01:00, or 2000-01-01 00:01:00+00:00
device__name string query No Filter metrics by exact device name
metric__name string query No Filter by the internal metric name identifier
parameter__name string query No Filter by the parameter's display name
parameter__short_name string query No Filter by the parameter's abbreviated name
parameter__variable_name string query No Filter by the parameter's variable name used in data collection
cursor string query No Pagination cursor for retrieving the next set of results
limit integer query No Number of results to return per page (default varies by system configuration)
metric_name string query No Alternative parameter to filter by metric's parameter name
parameter_name string query No Alternative parameter to filter by metric's parameter name

cURL Example:

curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?device__name=web-server-01&metric_name=memory_usage&datetime__gte=2024-01-15T00:00:00Z&limit=50" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Example Response:

{
  "count": 1247,
  "next": "https://control.zequenze.com/api/v1/inventory_metric_log/?cursor=eyJpZCI6MTAwfQ%3D%3D&limit=50",
  "previous": null,
  "results": [
    {
      "id": 15234,
      "datetime": "2024-01-15T14:30:00Z",
      "device": {
        "id": 42,
        "name": "web-server-01",
        "type": "server",
        "location": "datacenter-east"
      },
      "metric": {
        "id": 7,
        "name": "memory_usage",
        "unit": "percentage"
      },
      "parameter": {
        "name": "Memory Utilization",
        "short_name": "MEM",
        "variable_name": "memory_percent",
        "unit": "%"
      },
      "value": 67.8,
      "status": "normal",
      "created_at": "2024-01-15T14:30:15Z"
    },
    {
      "id": 15235,
      "datetime": "2024-01-15T14:25:00Z",
      "device": {
        "id": 42,
        "name": "web-server-01",
        "type": "server",
        "location": "datacenter-east"
      },
      "metric": {
        "id": 7,
        "name": "memory_usage",
        "unit": "percentage"
      },
      "parameter": {
        "name": "Memory Utilization",
        "short_name": "MEM",
        "variable_name": "memory_percent",
        "unit": "%"
      },
      "value": 65.2,
      "status": "normal",
      "created_at": "2024-01-15T14:25:15Z"
    }
  ]
}

Response Codes:

Status Description
200 Success - Returns paginated list of metric logs matching the filter criteria
400 Bad Request - Invalid query parameters or date format
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access metric data

GET /inventory_metric_log/{id}/

Description: Retrieves a specific inventory metric log record by its unique ID. This endpoint provides detailed information about a single metric entry, including all associated device, metric, and parameter data. Use this when you need complete details about a specific measurement or when following up on a particular data point identified in list queries.

Use Cases:

  • Get detailed information about a specific anomalous reading identified in monitoring
  • Retrieve complete metadata for a metric entry including collection timestamp
  • Verify specific measurements for audit or compliance purposes
  • Access full parameter details for a particular metric reading

Full URL Example:

https://control.zequenze.com/api/v1/inventory_metric_log/15234/

Parameters:

Parameter Type In Required Description
id integer path Yes Unique identifier of the metric log entry to retrieve
datetime__gte string query No Additional filter for datetime (though typically not needed for single record retrieval)
datetime__lte string query No Additional filter for datetime (though typically not needed for single record retrieval)
device__name string query No Additional filter by device name (for validation purposes)
metric_name string query No Additional filter by metric parameter name
parameter_name string query No Additional filter by parameter name
parameter__variable_name string query No Additional filter by parameter variable name

cURL Example:

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

Example Response:

{
  "id": 15234,
  "datetime": "2024-01-15T14:30:00Z",
  "device": {
    "id": 42,
    "name": "web-server-01",
    "type": "server",
    "model": "Dell PowerEdge R740",
    "serial_number": "ABC123XYZ789",
    "location": "datacenter-east",
    "rack": "R15-U24",
    "organization": "Production Web Services",
    "status": "active",
    "last_seen": "2024-01-15T14:30:00Z"
  },
  "metric": {
    "id": 7,
    "name": "memory_usage",
    "description": "System memory utilization percentage",
    "unit": "percentage",
    "collection_interval": 300,
    "retention_days": 90
  },
  "parameter": {
    "id": 23,
    "name": "Memory Utilization",
    "short_name": "MEM",
    "variable_name": "memory_percent",
    "description": "Percentage of total system memory currently in use",
    "unit": "%",
    "min_value": 0,
    "max_value": 100,
    "warning_threshold": 80,
    "critical_threshold": 95
  },
  "value": 67.8,
  "raw_value": "67.84329",
  "status": "normal",
  "quality": "good",
  "collection_method": "snmp",
  "created_at": "2024-01-15T14:30:15Z",
  "updated_at": "2024-01-15T14:30:15Z"
}

Response Codes:

Status Description
200 Success - Returns the specific metric log entry with complete details
401 Unauthorized - Invalid or missing authentication token
403 Forbidden - Insufficient permissions to access this metric data
404 Not Found - Metric log entry with the specified ID does not exist

Common Use Cases

Use Case 1: Building a Device Performance Dashboard

Retrieve recent metrics for multiple parameters from a specific device to display current status and short-term trends.

# Get last 24 hours of CPU, memory, and disk metrics for a server
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?device__name=web-server-01&datetime__gte=2024-01-15T00:00:00Z&limit=500" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 2: Historical Trend Analysis

Fetch metric data over a longer time period to analyze performance trends and identify patterns or seasonal variations.

# Get temperature readings for the past month
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?parameter__variable_name=temperature&datetime__gte=2023-12-15T00:00:00Z&datetime__lte=2024-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 3: Multi-Device Monitoring

Monitor the same metric across multiple devices by filtering on parameter name without specifying a device.

# Get CPU usage from all devices in the last hour
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?metric_name=cpu_usage&datetime__gte=2024-01-15T13:00:00Z&limit=1000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 4: Investigating Specific Incidents

When you identify an anomalous reading in your monitoring system, use the detail endpoint to get complete context about that specific measurement.

# Get full details about a specific concerning metric reading
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/15234/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Use Case 5: Data Export for External Analysis

Retrieve large datasets for import into external analytics tools or for compliance reporting.

# Export all metrics for a specific device over a quarter
curl -X GET "https://control.zequenze.com/api/v1/inventory_metric_log/?device__name=critical-server-01&datetime__gte=2024-01-01T00:00:00Z&datetime__lte=2024-03-31T23:59:59Z&limit=10000" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Best Practices

  • Use Date Range Filters: Always specify datetime filters (datetime__gte and datetime__lte) to avoid retrieving excessive historical data and improve response times.

  • Implement Pagination: For large datasets, use the limit parameter and pagination cursors to retrieve data in manageable chunks. Start with reasonable limits (100-500 records) and adjust based on your needs.

  • Cache Frequently Accessed Data: If building dashboards or reports that refresh frequently, consider caching metric data client-side for short periods to reduce API calls and improve user experience.

  • Combine Filters Effectively: Use multiple filter parameters together (device name + metric type + date range) to precisely target the data you need rather than filtering large result sets client-side.

  • Handle Rate Limits: Implement exponential backoff retry logic in your applications to handle potential rate limiting gracefully, especially when making bulk data requests.

  • Monitor API Usage: Track your API usage patterns to optimize query efficiency and avoid hitting rate limits during peak monitoring periods.

  • Validate Date Formats: Ensure datetime parameters are properly formatted in ISO 8601 format. Include timezone information when precision is important for your use case.

  • Use Appropriate Error Handling: Implement robust error handling for common scenarios like missing devices, invalid date ranges, and network timeouts, especially in automated monitoring systems.

Back to top