Property Values with Count API
Get unique values for alert properties along with their occurrence counts for analytics and filtering purposes.
Overview
This endpoint returns unique values for a specified alert property (field) along with the count of how many times each value appears. It's useful for creating filter dropdowns, analytics dashboards, and understanding data distribution in your alerts.
Note: Authorization Required: Include a valid Bearer Token in the Authorization header.
Endpoint Details
Request Body
paramstringrequired
The alert property field to analyze (e.g., "status", "severity", "dataSource")
paramarray
Optional filters to apply before analyzing the field values
paramstringrequired
Elasticsearch index pattern to search (typically "alert-*")
paraminteger
Maximum number of unique values to return
paramboolean
Whether to order results by count (true) or alphabetically (false)
paramboolean
Sort order: true for ascending, false for descending
JSON Schema
{
"type": "object",
"properties": {
"field": {
"type": "string",
"description": "Field name to analyze"
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": { "type": "string" },
"operator": { "type": "string" },
"value": { "oneOf": [{"type": "string"}, {"type": "integer"}, {"type": "array"}] }
}
},
"description": "Optional filters to apply"
},
"index": {
"type": "string",
"description": "Elasticsearch index pattern"
},
"top": {
"type": "integer",
"description": "Maximum number of results"
},
"orderByCount": {
"type": "boolean",
"description": "Order by count vs alphabetical"
},
"sortAsc": {
"type": "boolean",
"description": "Sort direction"
}
},
"required": ["field", "index"]
}Request & Response Examples
curl -X POST "https://demo.utmstack.com/api/elasticsearch/property/values-with-count"
-H "Authorization: Bearer <your_access_token>"
-H "Content-Type: application/json"
-d '{
"field": "severity",
"filters": [
{
"field": "@timestamp",
"operator": "IS_BETWEEN",
"value": ["now-7d", "now"]
}
],
"index": "alert-*",
"top": 10,
"orderByCount": true,
"sortAsc": false
}'[
{
"value": "2",
"count": 156
},
{
"value": "3",
"count": 89
},
{
"value": "1",
"count": 45
},
{
"value": "4",
"count": 23
},
{
"value": "5",
"count": 8
}
]Additional Code Examples
import axios from "axios";
const getPropertyValuesWithCount = async (field, options = {}) => {
const token = "<your_access_token>";
const payload = {
field: field,
filters: options.filters || [],
index: options.index || "alert-*",
top: options.top || 10,
orderByCount: options.orderByCount !== false,
sortAsc: options.sortAsc || false
};
try {
const response = await axios.post(
"https://demo.utmstack.com/api/elasticsearch/property/values-with-count",
payload,
{
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json"
}
}
);
console.log(`Top ${field} values:`, response.data);
return response.data;
} catch (error) {
console.error("Error getting property values:", error.response?.data || error.message);
}
};
// Usage examples
await getPropertyValuesWithCount("severity");
await getPropertyValuesWithCount("dataSource", { top: 20 });Response Details
Successful Response
Severity Analysis
[
{"value": "3", "count": 156},
{"value": "2", "count": 89},
{"value": "4", "count": 45},
{"value": "1", "count": 23},
{"value": "5", "count": 8}
]Data Source Analysis
[
{"value": "windows-server-01", "count": 234},
{"value": "firewall-main", "count": 178},
{"value": "web-server-prod", "count": 92},
{"value": "database-cluster", "count": 56}
]Empty Result
[]Status Codes
200OK
Successfully retrieved property values and counts
400Bad Request
Invalid field name, malformed filters, or invalid parameters
401Unauthorized
Missing or invalid Bearer token
500Internal Server Error
Internal server error during analysis
Common Use Cases
Filter Dropdown Population
// Populate severity filter dropdown
const populateSeverityFilter = async () => {
const severityValues = await getPropertyValuesWithCount("severity");
const dropdown = document.getElementById("severity-filter");
dropdown.innerHTML = '<option value="">All Severities</option>';
severityValues.forEach(item => {
const option = document.createElement("option");
option.value = item.value;
option.textContent = `Severity ${item.value} (${item.count})`;
dropdown.appendChild(option);
});
};Analytics Dashboard
// Create pie chart data for alert distribution
const createAlertDistributionChart = async () => {
const statusData = await getPropertyValuesWithCount("status", {
filters: [
{
field: "@timestamp",
operator: "IS_BETWEEN",
value: ["now-30d", "now"]
}
]
});
const chartData = {
labels: statusData.map(item => `Status ${item.value}`),
datasets: [{
data: statusData.map(item => item.count),
backgroundColor: ['#FF6384', '#36A2EB', '#FFCE56', '#4BC0C0']
}]
};
// Use with Chart.js or similar library
new Chart(ctx, {
type: 'pie',
data: chartData
});
};Top Offenders Report
def generate_top_offenders_report():
"""Generate report of top sources generating alerts"""
# Get top data sources
sources = get_property_values_with_count(
field="dataSource",
filters=[
{"field": "@timestamp", "operator": "IS_BETWEEN", "value": ["now-7d", "now"]},
{"field": "status", "operator": "IS_NOT", "value": 5} # Exclude completed
],
top=20
)
print("Top Alert Sources (Last 7 Days):")
print("=" * 50)
for i, source in enumerate(sources, 1):
percentage = (source['count'] / sum(s['count'] for s in sources)) * 100
print(f"{i:2d}. {source['value']:<30} {source['count']:>6} alerts ({percentage:.1f}%)")
return sourcesAdvanced Filtering Examples
Time-based Analysis
{
"field": "severity",
"filters": [
{
"field": "@timestamp",
"operator": "IS_BETWEEN",
"value": ["now-24h", "now"]
},
{
"field": "status",
"operator": "IS_IN",
"value": [2, 3]
}
],
"index": "alert-*",
"top": 5,
"orderByCount": true,
"sortAsc": false
}Exclude False Positives
{
"field": "dataSource",
"filters": [
{
"field": "tags",
"operator": "IS_NOT",
"value": "False positive"
},
{
"field": "severity",
"operator": "GREATER_EQUAL",
"value": 3
}
],
"index": "alert-*",
"top": 15,
"orderByCount": true,
"sortAsc": false
}Category Analysis
{
"field": "category",
"filters": [
{
"field": "@timestamp",
"operator": "IS_BETWEEN",
"value": ["now-30d", "now"]
}
],
"index": "alert-*",
"top": 25,
"orderByCount": true,
"sortAsc": false
}Performance Considerations
⚠️ Warning: Performance Tips:
Use appropriate
toplimits to avoid large result setsApply filters to reduce the data set being analyzed
Consider caching results for frequently requested fields
Use specific time ranges rather than analyzing all historical data
Monitor query performance for fields with high cardinality
Best Practices
[Unknown component: details]
[Unknown component: details]
[Unknown component: details]
OpenAPI Specification
post:
summary: "Get property values with occurrence counts"
tags:
- Alert Analytics
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PropertyValuesWithCountRequest'
responses:
'200':
description: "List of property values with counts"
content:
application/json:
schema:
type: array
items:
type: object
properties:
value:
type: string
description: "The property value"
count:
type: integer
description: "Number of occurrences"
'400':
description: "Invalid request parameters"
'401':
description: "Unauthorized"
'500':
description: "Internal server error"
components:
schemas:
PropertyValuesWithCountRequest:
type: object
required:
- field
- index
properties:
field:
type: string
description: "Field name to analyze"
filters:
type: array
items:
$ref: '#/components/schemas/FilterType'
description: "Optional filters to apply"
index:
type: string
description: "Elasticsearch index pattern"
top:
type: integer
default: 10
description: "Maximum number of results"
orderByCount:
type: boolean
default: true
description: "Order by count vs alphabetical"
sortAsc:
type: boolean
default: false
description: "Sort direction"