# Metric usage API Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdeveloper-portal%2Fapis%2Fdata-management%2Fmetrics-usage-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdeveloper-portal%2Fapis%2Fdata-management%2Fmetrics-usage-api.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.) 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[​](#query-parameters "Direct link to 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[​](#category-specific-filters "Direct link to 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[​](#field-reference "Direct link to 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-field-support-matrix "Direct link to 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[​](#when-to-use-each-field "Direct link to 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": "", "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).