---
title: trim_to() | Tiger Data Docs
description: Reduce the covered interval of a heartbeat aggregate
---

Since [1.16.0](https://github.com/timescale/timescaledb-toolkit/releases/tag/1.16.0)

Reduce the time range covered by a heartbeat aggregate. This can only be used to narrow the covered interval, passing arguments that would extend beyond the range covered by the initial aggregate gives an error.

## Samples

Given a table called `liveness` containing weekly heartbeat aggregates in column `health` with timestamp column `date`, use this query to roll up several weeks and trim the result to an exact month:

```
SELECT trim_to(rollup(health), '03-1-2022 UTC', '1 month')
FROM liveness
WHERE date > '02-21-2022 UTC' AND date < '3-7-2022 UTC'
```

## Arguments

The syntax is:

```
trim_to(
    agg HEARTBEATAGG,
    start TIMESTAMPTZ,
    duration INTERVAL
) RETURNS HEARTBEATAGG
```

| Name     | Type         | Default | Required | Description                                                                                                                                |
| -------- | ------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| agg      | HeartbeatAgg | -       | ✔        | A heartbeat aggregate to trim down                                                                                                         |
| start    | TimestampTz  | -       |          | The start of the trimmed range. If not provided, the returned heartbeat aggregate starts from the same time as the starting one            |
| duration | Interval     | -       |          | How long the resulting aggregate should cover. If not provided, the returned heartbeat aggregate ends at the same time as the starting one |

## Returns

| Column   | Type           | Description            |
| -------- | -------------- | ---------------------- |
| trim\_to | heartbeat\_agg | The trimmed aggregate. |