Property Values with Count API

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.

Authorization Required: Include a valid Bearer Token in the Authorization header.

Endpoint Details

POST /api/elasticsearch/property/values-with-count

Method: POST
Content-Type: application/json
Authentication: Bearer Token required
Response: Array of value/count objects

Request Body

field

string

required

The alert property field to analyze (e.g., “status”, “severity”, “dataSource”)

filters

array

Optional filters to apply before analyzing the field values

index

string

required

Elasticsearch index pattern to search (typically “alert-*”)

top

integer

default:"10"

Maximum number of unique values to return

orderByCount

boolean

default:"true"

Whether to order results by count (true) or alphabetically (false)

sortAsc

boolean

default:"false"

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
Data Source Analysis
Empty Result

[
  {"value": "3", "count": 156},
  {"value": "2", "count": 89},
  {"value": "4", "count": 45},
  {"value": "1", "count": 23},
  {"value": "5", "count": 8}
]

Status Codes

200

Successfully retrieved property values and counts

400

Bad Request

Invalid field name, malformed filters, or invalid parameters

401

Unauthorized

Missing or invalid Bearer token

500

Internal Server Error

Internal server error during analysis

Common Use Cases

// 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 sources

Advanced 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

Performance Tips:

Use appropriate top limits to avoid large result sets
Apply 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

Field Selection

Commonly analyzed fields:

severity - Alert severity levels
status - Alert status distribution
dataSource - Top alert sources
category - Alert categories
tactic - MITRE ATT&CK tactics
tags - Applied tags

Filter Strategy

Effective filtering:

Always include time filters to limit scope
Exclude false positives for meaningful analysis
Filter by status to focus on actionable alerts
Use severity filters for priority analysis

Result Limits

Appropriate limits:

Dropdowns: 10-20 items
Dashboard charts: 5-15 items
Reports: 20-50 items
Avoid requesting more than 100 items

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"

Getting Started

Authentication

Alert Management

Incident Management

Analytics & Utilities

Overview

Endpoint Details

POST /api/elasticsearch/property/values-with-count

Request Body

JSON Schema

Request & Response Examples

Additional Code Examples

Response Details

Successful Response

Status Codes

Common Use Cases

Analytics Dashboard

Top Offenders Report

Advanced Filtering Examples

Time-based Analysis

Exclude False Positives

Category Analysis

Performance Considerations

Best Practices

OpenAPI Specification

Getting Started

Authentication

Alert Management

Incident Management

Analytics & Utilities

​Overview

​Endpoint Details

POST /api/elasticsearch/property/values-with-count

​Request Body

​JSON Schema

​Request & Response Examples

​Additional Code Examples

​Response Details

​Successful Response

​Status Codes

​Common Use Cases

​Filter Dropdown Population

​Analytics Dashboard

​Top Offenders Report

​Advanced Filtering Examples

​Time-based Analysis

​Exclude False Positives

​Category Analysis

​Performance Considerations

​Best Practices

​OpenAPI Specification

Overview

Endpoint Details

Request Body

JSON Schema

Request & Response Examples

Additional Code Examples

Response Details

Successful Response

Status Codes

Common Use Cases

Filter Dropdown Population

Analytics Dashboard

Top Offenders Report

Advanced Filtering Examples

Time-based Analysis

Exclude False Positives

Category Analysis

Performance Considerations

Best Practices

OpenAPI Specification