Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fuser-guides%2Fdata-layer%2Fsystem_dataspace%2Fdataplan-usage-events.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%2Fuser-guides%2Fdata-layer%2Fsystem_dataspace%2Fdataplan-usage-events.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# `dataplan.usage_events`

The `dataplan.usage_events` dataset stores aggregated data usage events for your team. Each event captures a unit of ingestion after ratios have been applied, letting you query your team's consumption alongside any other data in Coralogix using [DataPrime](https://docs-docusaurus.kinsta.page/dataprime/introduction/welcome-to-the-dataprime-reference/.md).

Use this dataset to analyze usage trends, build custom dashboards and alerts on top of raw usage events, and correlate consumption with other telemetry — without relying solely on the Data Usage page.

## Enable the dataset[​](#enable-the-dataset "Direct link to Enable the dataset")

The dataset is exposed through Coralogix's dataset management and is populated only when ingestion is enabled for `dataplan.usage_events`.

1. In the navigation bar, select **Settings**, then **Data Usage**.
2. Select **Settings** in the top-right actions bar to open the Data Usage settings panel.
3. In the **data.usage.history** row, select **Enable data.usage.history**. Coralogix takes you to **Dataspace management**, where you can enable write access for the `dataplan.usage_events` system dataset.

Once ingestion is enabled, new usage events are written to the dataset as they are aggregated. You can return to the settings panel to open the dataset directly in Explore with **View dataset in Explore**.

## Query the dataset[​](#query-the-dataset "Direct link to Query the dataset")

Query `dataplan.usage_events` using DataPrime:

```
source system/"dataplan.usage_events"
```

Filter and aggregate like any other dataset:

```
source system/"dataplan.usage_events"

| filter $d.labels.pillar == "logs"

| groupby $d.labels.applicationname aggregate sum($d.measurement.consumed_cx_units) as units
```

## Schema description[​](#schema-description "Direct link to Schema description")

Each event represents one aggregated bucket of team data usage for a given logical key and time window, published by Coralogix's data usage exporter after unit ratios have been applied.

| Field                              | Type               | Description                                                                                                                                                                                                                               |
| ---------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$d.measurement`                   | object             | The aggregated measurement for the bucket.                                                                                                                                                                                                |
| `$d.measurement.value`             | integer            | Raw measured value for the bucket.                                                                                                                                                                                                        |
| `$d.measurement.kind`              | string             | Measurement kind — for example, `processed_data_size`, `egress_data_size`, `events`, `samples`, `tokens`, or `olly`.                                                                                                                      |
| `$d.measurement.unit`              | string             | Unit of the raw measured value — for example, `bytes`, `events`, `samples`, or `tokens`.                                                                                                                                                  |
| `$d.measurement.consumed_cx_units` | number             | Billable Coralogix units consumed by the raw measured value.                                                                                                                                                                              |
| `$d.timestamp`                     | string (date-time) | UTC timestamp for the usage bucket.                                                                                                                                                                                                       |
| `$d.bucket_duration_millis`        | integer            | Duration of the aggregated usage bucket, in milliseconds.                                                                                                                                                                                 |
| `$d.labels`                        | object             | String-to-string map of Coralogix and user labels for the record. Commonly present keys: `pillar`, `entity_type`, `priority`, `severity`, `feature_id`, `feature_group_id`, `data_space`, `data_set`, `applicationname`, `subsystemname`. |

Note

`$d.labels` is a dynamic string map — reference an individual label as `$d.labels.<key>` (for example, `$d.labels.pillar`). Label values for `severity` and `priority` are lowercase.

## Example queries[​](#example-queries "Direct link to Example queries")

Consumed Coralogix units by pillar:

```
source system/"dataplan.usage_events"

| groupby $d.labels.pillar aggregate sum($d.measurement.consumed_cx_units) as units

| orderby units desc
```

Raw bytes ingested by application over the last 24 hours:

```
source system/"dataplan.usage_events"

| filter $d.timestamp > now() - 24h && $d.measurement.kind == "processed_data_size"

| groupby $d.labels.applicationname aggregate sum($d.measurement.value) as total_bytes

| orderby total_bytes desc

| limit 5
```

## Notes and limits[​](#notes-and-limits "Direct link to Notes and limits")

* `dataplan.usage_events` is a `system` dataset maintained by Coralogix. Like other system datasets, events count toward your daily quota; volumes are typically small compared to your user data.
* Each event is one aggregated bucket; multiple raw events may be merged into a single usage event per logical key and time window.

## Next steps[​](#next-steps "Direct link to Next steps")

* Manage dataset access and retention in [Dataset management](https://docs-docusaurus.kinsta.page/user-guides/data-layer/dataset-management/.md).
* Track quota activity with [`dataplan.quota_events`](https://docs-docusaurus.kinsta.page/user-guides/data-layer/system_dataspace/quota_events/.md).
* Audit account actions with [`aaa.audit_events`](https://docs-docusaurus.kinsta.page/user-guides/data-layer/system_dataspace/aaa_audit-events/.md).