Metric Usage API

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:

seriesByMetricName: Provides a list of metric names and their usage.
seriesByLabelName: Provides a list of label names and their usage.
seriesByVariationForMetric: For a given metric, provides a list of variations (distinct label sets) and their usage.
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:

metric_name_filter: Substring filter for metric names.
label_name_filter: Substring filter for label names.
metric_name: When scoping to a single metric (required for variation/label-by-metric calls).
label_name: When scoping to a single label (required for metric-by-label calls).
label_names_filter: Optional list of label names; each must match part of at least one label in a variation.

Defaults will be used if optional fields are omitted.

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..coralogix.com:443 with your region domain (e.g., api.eu2.coralogix.com:443).

Previous Metrics Cost Optimizer API

Next Insights API