---
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 < '4-4-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 | HeartbeatAgg | The trimmed aggregate. |
