# Metric rollups and resolution

Understand metric resolution, rollup buckets, aggregations, and how single values differ from statistic sets.

Resolution controls how metric data is grouped over time. It affects metric detail charts, dashboard charts, alarms, and API queries.

Use this guide when a chart looks too detailed, too smooth, or when `count`, `avg`, `max`, percentile, or trimmed mean values do not match what you expected.

## What resolution means

Resolution is the bucket size in seconds.

When you query a metric at `60` second resolution, each returned point represents one one-minute bucket. When you query at `300` second resolution, each returned point represents one five-minute bucket.

Smaller resolutions show more detail. Larger resolutions summarize more data into fewer points, which makes long time ranges easier to read.

## Resolution when sending metrics

Each metric entry can include a `resolution`.

If `resolution` is omitted, the API stores the point at one-second resolution. If you send `resolution: 60`, the point represents a one-minute bucket.

Choose a send resolution that matches how often the data was measured or flushed:

- use `1` for high-frequency raw samples;
- use `60` for values emitted once per minute;
- use a larger value when a job already summarizes a longer interval.

When querying later, choose the resolution that matches the question you are asking. It does not have to match the resolution used when the metric was sent.

See [Send your first metric](/docs/send-metric) for request examples.

## Single values

A single `value` represents one observation at one timestamp.

The API stores that observation with a sample count of `1`. If the value is queried alone:

- `min`, `max`, and `avg` return the value;
- `count` returns `1`;
- `sum` returns the value.

When several single values fall into the same query bucket, the selected aggregation is calculated across those values.

## Statistic sets

A `statisticSet` represents several observations that were already summarized before sending.

It includes:

- `min`: the smallest observed value;
- `max`: the largest observed value;
- `avg`: the average value;
- `sampleCount`: how many observations the set represents.

Use statistic sets when a client, agent, or batch job buffers observations and flushes them later. This keeps payloads smaller while preserving the data needed for rollups.

`count` uses `sampleCount`. If a query bucket contains multiple statistic sets, `count` returns the sum of their `sampleCount` values.

## How rollups affect aggregations

When the query resolution is larger than the stored resolution, multiple source buckets are rolled up into one returned bucket.

The returned aggregation is calculated from the data represented by the source buckets:

- `min` returns the smallest value in the returned bucket;
- `max` returns the largest value in the returned bucket;
- `avg` returns the weighted average using sample counts;
- `count` returns the total sample count;
- `sum` returns the summed values represented by the bucket;
- `percentile(95)` returns the requested percentile for the bucket;
- `trimmed_mean(10;10)` returns the average after trimming the lower and upper percentages from the bucket.

`percentile(...)` and `trimmed_mean(...)` are accurate for data sent as individual `value` entries. For `statisticSet` sources only the per-set average is available, so those distribution aggregations approximate toward the mean.

For example, if six one-minute buckets are queried at `300` second resolution, the chart returns one point for each five-minute group. The one-minute detail is summarized into that larger point.

## Choosing resolution in the UI

The time range picker controls the query window and resolution for metric detail pages, dashboards, and alarm previews.

Use short ranges with smaller resolutions when investigating a recent spike. Use longer ranges with larger resolutions when looking for trends.

Practical starting points:

- last hour: `1m` often gives enough detail;
- last day: `5m` or `15m` is easier to scan;
- last week: larger buckets are usually better for trends.

If a chart looks noisy, increase the resolution. If a spike disappears, lower the resolution or narrow the time range.

## Resolution in alarms

Alarm resolution controls the buckets used during evaluation.

Match alarm resolution to the reporting frequency of the metric. A metric reported once per minute usually works well with `1m`. A metric reported every few seconds may need a shorter resolution. A batch metric that reports every five minutes should not use a one-minute alarm resolution.

Use **Datapoints to Alarm** together with resolution to control sensitivity. For example, requiring several breaching buckets avoids alerting on a single short spike.

See [Create an alarm](/docs/alarms) for the alarm setup flow.

## Common surprises

`count` is sample count, not number of API requests. A single API request can send many entries, and one statistic set can represent many samples.

`avg` across statistic sets is weighted by `sampleCount`. A statistic set with `sampleCount: 100` has more weight than one with `sampleCount: 1`.

Large resolutions can hide short spikes because several smaller buckets are summarized into one point.

The query resolution is a viewing choice. Change it freely to trade detail for readability.