> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mangrovesystems.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data capture rate

> Measure data completeness: find missing data and gaps where a sensor or feed stopped reporting, before a reporting deadline.

Data capture rate is the share of the data you expected that actually arrived. You declare how often an event type should report, and Mangrove compares that expectation against the measurements it holds: expect 720 hourly measurements in a month, receive 690, and your capture rate is 95.8%.

A data rule checks the values you have. This finds the ones that never came.

```mermaid theme={null}
pie showData
    title Expected hourly values in a month
    "Measured" : 690
    "Substituted" : 18
    "Missing" : 12
```

The whole circle is what the cadence expected. Only the measured slice counts toward the rate.

<Note>
  Data capture rate is switched on per account. Ask your Mangrove account team to switch it on if the **Cadence** field described here is not in your project yet.
</Note>

## What a low rate means

A capture rate below what you expected is almost always one of three things:

| Cause                                               | How to tell                                              | What to do                                                                                                       |
| --------------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| A feed or sensor stopped delivering                 | The **Missing** count is high and clustered in time      | Check the data feed, then backfill the period                                                                    |
| The cadence is tighter than the data really arrives | **Missing** is spread evenly across the whole range      | Correct the cadence on the event type                                                                            |
| Gaps were filled by substitution                    | The **Substituted** count is high and **Missing** is low | Nothing is missing; the data is estimated rather than measured, and a substituted value never counts as captured |

**Missing** is the line to chase. To see exactly which values are absent rather than how many, filter the **Value** column with the **Is missing** operator on the Events table. See [Review data points](/data-collection/data-points).

Mangrove does not block a report on a low capture rate, and the figure is not part of the package an auditor downloads. What the auditor does see is the substitution summary in each batch workbook, so a gap you filled is visible to them even though the rate itself is not. See [Share a report with an auditor](/reporting/audit-hub).

## Declare a cadence

Cadence sits on the event type, so every data point type under it shares one expectation.

1. Open **Data Inputs**, then **Settings**.
2. Add an event type, or edit an existing one.
3. Expand **show settings** and set **Cadence**.

Pick a preset, from every minute up to every month, or choose **Custom** and give an amount and a unit. Leave it on **Irregular** for anything that arrives when it arrives, such as shipments or lab results. Irregular data has no schedule to measure against, so Mangrove never reports it as short.

<Note>
  `1 day` and `24 hour` are different declarations. Days, weeks, months and years are calendar periods in your account's timezone; hours, minutes and seconds are elapsed time. From `month` upward a value counts toward the period it falls in, so a monthly meter figure filed on the 28th still counts for that month.
</Note>

## Where to find the figure

The capture rate sits on the **Events** table toolbar under Data Inputs, beside the **Event / data point type** quick filter. Narrow to one data point type and it shows that type's percentage. With several in view it shows a count, and opens into a list of every data point type in scope, worst first.

It always measures against a date range. With a data point type selected and no range of your own, it covers the year to date.

A rate just under 100 shows as "under 100%" rather than rounding up, so a data point type that is one value short never reads as complete.

Three states appear instead of a percentage:

| It shows             | Meaning                                                                                                                                        | What to do                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| **Not measurable**   | A cadence is declared, but nothing was expected in this range, because the event type has never reported or the range predates its first data. | Widen the date range, or check the event type is receiving data.            |
| **Not computed yet** | The cadence is set and the figure has not been worked out yet.                                                                                 | Wait for the overnight run, or use **Recompute**.                           |
| Greyed out           | Nothing to measure: no date range, no data point type selected, or the selected type's event type has no cadence.                              | Set a date range, or pick a data point type whose event type has a cadence. |

Open the figure on a single data point type to break the shortfall down: how many values were expected, how many were captured, and what the rest were. **Substituted** counts values a correction supplied. **Missing** counts values that never arrived.

## What counts as captured

Only a measurement counts toward the capture rate. A substituted value is an estimate, so it does not count, but it is reported separately rather than folded into the gap.

The expectation starts at the first event recorded for that event type, and the current period is measured one interval behind so a value still in transit is not counted as missing. Figures update as data changes and are rebuilt overnight.

## Alert when data stops arriving

Once an event type declares a cadence, a data rule can act on the capture rate with `DATA_CAPTURE_RATE`, so you are told about a gap instead of going to look for one. See [Create a data rule](/data-rules/create-a-rule).

```
DATA_CAPTURE_RATE({{data-point.ambient-temperature-c}} WITHIN CALENDAR MONTH) < 0.8
```

`DATA_CAPTURE_RATE` returns a fraction between 0 and 1, so compare against `0.8` rather than `80`. See [Rule Expressions](/data-rules/rule-expressions) for the windows it accepts and the conditions it rejects.

## Cadence over the API

A cadence is readable and writable on the event type endpoints as `cadence_amount` and `cadence_unit`. Both are null when no cadence is declared.

* [Retrieve an event type](/api-reference/event-types/get)
* [Update an event type](/api-reference/event-types/patch)

An event type carries both fields or neither. An update merges with what is stored, so sending one field changes half of a cadence that already exists, while sending one on its own when no cadence is set returns `422`. To clear a cadence, send both as `null`.

On an account without the feature, `cadence_amount` and `cadence_unit` are dropped from the request instead of rejected. The update returns `200` and the cadence is unchanged, so check the response rather than assuming the write landed.