Metric usage API

Open in ChatGPTOpen in Claude

With Coralogix you can retrieve detailed usage for your metrics (bytes volume, series/cardinality, samples, and derived unit usage) over calendar dates in multiple categories. Our API returns usage statistics by dates* in 4 categories:

1. seriesByMetricName: Provides a list of metric names and their usage.
2. seriesByLabelName: Provides a list of label names and their usage.
3. seriesByVariationForMetric: For a given metric, provides a list of variations (distinct label sets) and their usage.
4. seriesByMetricForLabel: For a given label, provides a list of metrics and their usage.

• Dates are in UTC.

URL: Select the Metrics Usage API endpoint associated with your Coralogix domain.

Method: gRPC (TLS)

Authorization: To use this API you need to create a personal or team API key. It’s recommended to use permission presets, as they are automatically updated with all relevant permissions. Alternatively, you can manually add individual permissions.

Preset	Action	Description
DataAnalytics	LOGS.DATA-ANALYTICS#HIGH:READ METRICS.DATA-ANALYTICS#HIGH:READ	View analytics data for Logs and Metrics, including Frequent Search Mapping Statistics and Metrics Analytics.

Query parameters

Common fields (used by list-style calls):

• start_date: The oldest date that will be included in the statistics response.
  • It can’t be in the future.
  • It can’t be after end_date.
• end_date: The most recent date that will be included in the statistics response.
  • It can’t be in the future.
  • It can’t be before start_date.
• start_offset: Zero-based offset of the first item to return (default: 0).
• length: Maximum number of items to return.
• order_by: Sort key. One of BYTES_VOLUME, CARDINALITY, SAMPLE_COUNT.
• ordering: Sort direction. DESCENDING (default) or ASCENDING.

Category-specific filters

Each RPC supports a different set of category-specific fields. Use this table to see which fields you can include for each method. Fields not listed under Required or Optional are considered Not supported.

Field reference

These are the only category-specific fields used across the RPCs:

• metric_name
• metric_name_filter
• label_name
• label_name_filter
• label_names_filter

RPC field support matrix

RPC method	Required	Optional
GetMetricUsages	-	metric_name_filter
GetSingleMetricUsage	metric_name	label_name_filter
GetVariationUsagesByMetric	metric_name	label_names_filter
GetLabelUsages	-	label_name_filter
GetSingleLabelUsage	label_name	metric_name_filter
GetLabelUsagesByMetric	metric_name	label_name_filter
GetMetricUsagesByLabel	label_name	metric_name_filter, label_name_filter
GetTotalMetricUsages	-	, only common fields supported

When to use each field

• metric_name: Use when the RPC targets a single metric.
• metric_name_filter: Use to return only metrics whose names match a substring.
• label_name: Use when the RPC targets a single label.
• label_name_filter: Use to filter results by label name substring.
• label_names_filter: Use to filter variation-level results by requiring that at least one label matches.

Example #1: GetMetricUsages with start_date, end_date, and paging.

grpcurl \
    -H 'Authorization: cxup_<...>' \
    -d '{"common":{"start_date":{"year":2025,"month":9,"day":11},"end_date":{"year":2025,"month":9,"day":11},"start_offset":0,"length":10}}' \
    api.eu2.coralogix.com:443 \
    com.coralogix.metrics.metric_usages.UsageService.GetMetricUsages

Output:

{
  "daily_usages": [
    {
      "total_daily_usage": {
        "date": {"year": 2025, "month": 9, "day": 11},
        "daily_cardinality": "...",
        "daily_bytes_volume": "...",
        "daily_unit_usage": 0.0
      },
      "output_set_stats": {"matched_count": 0},
      "metric_usages": [
        {
          "name": "<metric>",
          "usage": {
            "cardinality": "...",
            "fraction_of_daily_cardinality": 0.0,
            "bytes_volume": "...",
            "unit_usage": 0.0,
            "fraction_of_daily_usage": 0.0
          },
          "sample_count": "...",
          "fraction_of_daily_sample_count": 0.0,
          "dimensions_count": 0,
          "variations_count": 0,
          "ingestion_time_stats": {
            "first_ingested_epoch_seconds": 0,
            "last_ingested_epoch_seconds": 0
          }
        }
      ],
      "total_sample_count": "..."
    }
  ]
}

Example #2: GetVariationUsagesByMetric with all optional fields omitted.

grpcurl \
    -H 'Authorization: cxup_<...>' \
    -d '{"common":{"start_date":{"year":2025,"month":9,"day":11},"end_date":{"year":2025,"month":9,"day":11}},"metric_name":"http_requests_total"}' \
    api.eu2.coralogix.com:443 \
    com.coralogix.metrics.metric_usages.UsageService.GetVariationUsagesByMetric

Output:

{
  "daily_usages": [
    {
      "metric_daily_usage": {
        "date": {"year": 2025, "month": 9, "day": 11},
        "daily_cardinality": "...",
        "daily_bytes_volume": "...",
        "daily_unit_usage": 0.0
      },
      "output_set_stats": {"matched_count": 0},
      "variation_usages": [
        {
          "label_names": ["method=GET"],
          "usage": {
            "cardinality": "...",
            "fraction_of_daily_cardinality": 0.0,
            "bytes_volume": "...",
            "unit_usage": 0.0,
            "fraction_of_daily_usage": 0.0
          },
          "sample_count": "...",
          "fraction_of_daily_sample_count": 0.0,
          "ingestion_time_stats": {
            "first_ingested_epoch_seconds": 0,
            "last_ingested_epoch_seconds": 0
          }
        }
      ],
      "total_sample_count": "..."
    }
  ]
}

Note

Replace api.<region>.coralogix.com:443 with your region domain (e.g., api.eu2.coralogix.com:443).