Reports

Build, run, schedule and export reports on your sensor readings, alerts and hub activity from the Reports page.

In the app: /reports

Reports#

Reports let you pull your own history out of RoamVitals: a table of readings, a list of alerts, or a count of how much data each sensor sent. You can run a report once and download it, save it to run again later, or have it emailed to you on a schedule.

Open Reports from the navigation - the side menu on a computer, the bottom bar on a phone - or go to /reports.

What is on the page#

The page has three parts.

• Saved Reports lists the reports you have saved, with the columns Name, Source and Actions. On a wide screen it sits on the left of the builder; on a narrow screen it sits above it. Before you save anything it says "No saved reports yet - build one on the right and save it. Reports sync to your hub."
• New Report / Edit Report is the builder. The heading changes to Edit Report once you click a saved report's name.
• Result appears underneath after you run something, and the page scrolls down to it.

Build and run a report#

1. Click New Report at the top right if the builder is not already empty.
2. Type a Report name. If you leave it blank and save, it is stored as Untitled report.
3. Pick a Data source (see the table below).
4. Pick a Time window: Last hour, Last 6 hours, Last 24 hours, Last 7 days, Last 30 days or Last 90 days.
5. For sensor readings, pick a Detail level and any Sensors.
6. Choose Show as, a Row limit and a Sort direction.
7. Click Run Report. The result appears at the bottom of the page.
8. Click Save Report if you want to keep it. The button says Update Report when you are editing one you already saved.

An empty builder is not a blank one. It starts on Sensor readings, Last 24 hours, Automatic detail, Line chart, a Row limit of 100 and Newest first, so pressing Run Report straight away gives you a day of readings from your sensors.

Run Report runs exactly what is on screen right now, saved or not. It is fine to run a report you never intend to keep.

The four data sources#

A few things that follow from this:

• The Sensors picker and Detail level only appear for Sensor readings. The Severity picker only appears for Alerts & events; you can tick any of info, warning and critical, and it reads "All severities" while none are ticked.
• Alerts & events and Hub activity always cover every sensor on the hubs you own and nothing else. Neither has a sensor picker, and neither reaches a hub that was shared with you.
• Hub activity is always ordered by the busiest sensor first. The Sort control does not change it. A sensor that recorded nothing in the window is left out rather than listed with a zero.
• Custom query (advanced) cannot be run. If you try, you get "Custom query reports are definitions only - they cannot be run here." A saved one gives "This report is a custom-query definition and cannot be run here."

Time window and detail level#

The time window is always relative to the moment you run the report. There is no calendar picker, so "Last 7 days" means the last seven days from now, not a fixed week.

Detail level decides whether you get every reading or a summary per time bucket. Leaving it on Automatic picks a sensible bucket for the window you chose:

You can override it with Every reading (raw), 15-minute summary, Hourly summary, 6-hour summary or Daily summary.

Summaries give you Average, Min, Max and Samples for each bucket. Gaps stay gaps: a bucket with no data produces no row rather than a zero.

Your plan limits how far back your history is kept, and every report is trimmed to that limit whatever window you pick. This applies to all three runnable sources: readings and alerts older than your limit have already been deleted, so a wider window does not bring them back. The Data Retention row in the Subscription section of Settings shows your limit.

Choosing sensors#

The Sensors (empty = all your sensors) box lists sensors by name across your hubs.

• Leave it empty and the report covers the sensors on hubs you own.
• If a hub was shared with you as a read-only viewer, its sensors are not included automatically. Pick them by name to include them.
• A report reads at most 25 sensors either way. If you pick more, only the first 25 you picked are read. If you own more than 25 and leave the box empty, 25 are read and there is no saying which 25. Keep the selection tight.

Show as, row limit and sort#

• Show as: Table, Line chart, Bar chart or Single number. Line chart and Bar chart both draw the same line chart above the table. Single number shows the most recent value of the first series in large type, with that series' name under it. Whatever you choose, the table is always shown underneath.
• The chart draws at most four lines, and each line is scaled to its own range, so where two lines sit relative to each other means nothing. The caption under it says as much: "Each line is scaled to its own range." A line also needs at least two points, so a run that produced a single bucket draws nothing at all.
• Charts and the single number only work when the result has a time column and a value column, which means the Sensor readings source. Alerts and hub activity always come back as a plain table.
• Row limit: between 1 and 5000, default 100. If the data goes past the limit, the result line says "truncated to the row limit".
• Sort: Newest first or Oldest first.

If you change any of these after running, click Run Report again. The Result panel does not update on its own.

Reading the Result panel#

The heading reads Result - <your report name>, followed by a summary line such as:

72 rows · last 24h · 1h detail

The table shows the first 500 rows. Past that you see "Showing the first 500 of N rows - download the CSV for everything." Times are shortened to your device's local time zone and numbers are rounded to two decimals for display only.

For Sensor readings, the Sensor column shows the sensor's internal ID rather than the name you gave it, and Metric shows the raw metric key such as temperature_c or battery_pct. Charts label each line with that sensor ID followed by a friendly metric name, for example Temperature, and the legend under the chart only appears when there is more than one line. Alerts and hub activity show the sensor name instead.

Worked example: an overnight temperature check#

1. Report name: Overnight temperature check
2. Data source: Sensor readings
3. Time window: Last 24 hours
4. Detail level: Hourly summary
5. Sensors: choose Fridge
6. Show as: Line chart, Row limit: 100, Sort: Newest first
7. Click Run Report.

You get a line per metric above a table like this:

The Time column is drawn in your device's local time and its own date format, so yours may read slightly differently. One row is one bucket per metric, so a sensor reporting three metrics across 24 hourly buckets is the 72 rows on the summary line.

Click Save Report and it appears in Saved Reports with the source sensors_readings, and the app confirms "Report saved - it syncs to your hub."

Click Download CSV and the file Overnight temperature check.csv starts with:

Time,Sensor,Metric,Average,Min,Max,Samples
2026-08-16T02:00:00+00:00,3f9c1b2e-7a41-4d0e-9c55-1b2c3d4e5f60,temperature_c,4.208333333333333,3.9,4.6,12

The CSV keeps the full timestamp and full precision. The screen rounds, the file does not.

Working with saved reports#

In the Saved Reports table:

• Click the Name to load that report into the builder for editing.
• The play icon (Run) runs the saved version and drops the result at the bottom of the page.
• The PDF icon (Download PDF) runs the saved version and downloads it as a PDF.
• The red trash icon (Delete) asks Delete report "<name>"? before removing it.
• A scheduled chip next to the name means email delivery is switched on.

Run, PDF and scheduled email all use the last saved version of the report. Unsaved edits in the builder only affect the Run Report button.

Emailing a report on a schedule#

Open the Email schedule section in the builder. The header shows the current setting, for example "Email schedule - daily at 07:00", or "(off)" when it is disabled.

1. Turn on Email this report to me on a schedule.
2. Pick a Frequency: Daily, Weekly or Monthly.
3. Set a Time, for example 07:00. It follows the time zone of the browser you set it up in.
4. Pick an Attachment: CSV, PDF or None (inline).
5. Click Save Report or Update Report. Nothing is scheduled until you save. The section reminds you: "Sent to your account email. Save the report to apply schedule changes."

What to expect:

• The email goes to the address in the Email field of the Account section on the Settings page. Report email is separate from the Notifications settings, so you do not need Email me switched on for reports.
• The subject is [RVMonitor] Report: <your report name>.
• The body always contains the report table (first 200 rows) and, where the data can be charted, a chart. That chart labels its lines with the raw metric key, such as temperature_c, rather than the friendly name the on-screen chart uses. CSV and PDF attach an extra copy of the same run; None (inline) sends the body with no file attached.
• Weekly sends on Mondays and Monthly sends on the 1st. The web builder does not offer a day picker.
• Delivery is checked about every five minutes, so the email can arrive a few minutes after the time you set.
• The first email usually turns up at that next check rather than waiting for the time you chose, because a schedule that has never run counts as due. After that it settles into the frequency you picked.
• If you choose the PDF attachment and the server cannot render PDFs, you get a CSV attachment instead rather than no email.
• Custom query reports are skipped by the scheduler.

Exporting#

• CSV: run the report, then click Download CSV in the Result panel. The file is named after the report.
• PDF: click the PDF icon on the row in Saved Reports. The PDF contains the same header line, a chart when the data can be charted, and the first 200 rows.

If PDF rendering is not installed on the server you will see "PDF rendering is not available on this server - use the CSV download instead." Any other PDF failure, including asking for a PDF of a custom query report, gives "Could not render the PDF."

Advanced filters (JSON)#

Under Advanced filters (optional JSON) you can type the filter block yourself. This section is hidden when Interface mode in Settings is set to "Keep it simple (essentials only)"; switch it to "Full control (everything)" to see it.

Use it when you need something the guided controls do not offer, most often narrowing to specific metrics:

{"window": "24h", "interval": "1h", "sensor_ids": ["3f9c1b2e-7a41-4d0e-9c55-1b2c3d4e5f60"], "metric_keys": ["temperature_c"]}

Two things to know:

• The JSON replaces the guided filters completely, so include everything you need in it, not just the new key.
• If the JSON does not parse, it is ignored silently and the guided filters are used instead. If a run looks like your JSON had no effect, check for a missing comma or quote.

Filter keys that actually do something: window on any runnable source; interval, sensor_ids and metric_keys on sensor readings; severity on alerts and events.

The JSON is saved with the report when you press Save, and it stays in effect the next time you open it, even though the box appears empty again.

Putting a report on your dashboard#

1. Go to the Dashboard and click Edit layout. If you have never customized it, the button says Customize dashboard instead.
2. Click Add widget.
3. Choose Report Result ("Live result of a saved report."). The entry is greyed out until you have saved at least one report.
4. Pick which saved report to show.
5. Click Save to keep the layout.

The widget runs that report each time it loads and shows its chart, or the row count if the data cannot be charted. While it is working it says "Running…", and if the run fails it says "Could not run this report here."

There is also a Saved Reports widget that just counts how many reports you keep.

What to do if#

"Could not run the report." The run failed. Try a shorter time window or fewer sensors, then run it again. The play icon in Saved Reports shows this one line for any failure other than a custom query, so to see the actual reason, load the report into the builder and press Run Report there.

"Sensor not found:" followed by an ID. The report names a sensor that no longer exists. Load the report into the builder, take that sensor out of Sensors, and save it again.

The result is empty. Either nothing was recorded in that window, or the window reaches back past your plan's data retention. Widen the sensor selection, shorten the window, or check the sensor is still reporting on its sensor page.

The chart area is blank. Charts need a time column and a value column, so set the data source to Sensor readings, or set Show as to Table for alerts and hub activity. A chart also needs at least two points per line, so a result with a single bucket draws nothing.

The numbers on screen look rounded. They are, to two decimals. Download the CSV for full precision.

Only part of the data came back. Look for "truncated to the row limit" on the result line, then raise the Row limit (up to 5000) or use a coarser Detail level. On a summary detail level the rows that survive truncation are the earliest ones in the window, even when the sort says Newest first; Every reading (raw) keeps the end you sorted to.

A sensor you picked is missing from the results. A report reads at most 25 sensors, and read-only shared hubs are only included when you pick their sensors by name.

The scheduled email never arrived. Check the address in the Account section of Settings, confirm the report shows the scheduled chip in the list (if not, you did not save after switching it on), and remember the report has to be runnable, so a custom query report will never be sent. If it still does not arrive, contact support: scheduled email delivery has to be enabled on the server side.