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

```text
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:

```text
{
  "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.

```text
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:

```text
{
  "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).