Folder and tag rollups
fleet_health, uptime, publishing and alerts roll the fleet up by folder, screen or tag over inclusive UTC days. A folder row counts every screen in it and in every folder inside it, and the first row is the whole project. Tags are the second grouping: a screen counts in each tag it carries.
| Report | What a row says |
|---|---|
fleet_health | Screens, online now, availability, open alerts, alerts begun in the period, hot, display disconnected, crashing, and how many screens run their current content |
uptime | Online and offline hours, availability and recorded coverage |
publishing | Screens with current content, updating content, content that needs attention and no content |
alerts | Alerts open now and begun in the period, by condition |
alert_log | One row per alert that began in the period: the screen, the condition, when it began and ended, and who acknowledged it |
proof_of_play | Plays of a sponsor's or advertiser's direct campaigns per campaign, media and screen, with totals |
GET /api/reports lists the kinds and the filters each takes (screenrig reports list). GET /api/reports/{kind} builds a report (screenrig reports show KIND, with each filter as a flag: --from, --to, --group-by, --folder-id, --direct, --tag, --campaign-id, --advertiser). from and to are UTC days (default: the last 30 days; at most 366 days apart); group_by is folder (default), screen or tag; folder_id limits the report to a folder and everything inside it, and with direct=true to the folder and its child folders, or, grouped by screen, to the screens directly in it; tag keeps screens carrying that tag. A folder row carries id, parent_id and depth, so a client draws the outline from the rows. Availability is online time over recorded time, and recorded coverage says how much of the period the screens reported a state.
The Screen health tab of the dashboard's Logs page lays these rollups out as the screen folders: each folder opens to its subfolders and its screens, and each screen to its Health tab. The Screen reports tab builds any of the reports, with the same filters, and downloads it as CSV, Excel or PDF.
CSV, XLSX and PDF
Every report route takes format=csv, xlsx or pdf and answers with an attachment of the same rows: the new reports, GET /api/uptime/daily, GET /api/screens/{id}/uptime, GET /api/screens/{id}/health/history, GET /api/health/trend, GET /api/alerts, GET /api/playback, GET /api/playback/plays, GET /api/playback/totals, GET /api/playback/completeness, the advertising delivery, fill and spend reports and a direct campaign's report. A paged report is written whole, up to 50,000 rows; truncated says when it holds only the first rows.
The XLSX file is one sheet with the title and period above a frozen header, numbers as numbers and the totals in bold. The PDF is a plain statement with the screenRIG name, the project it is for, the title and period, a table whose header repeats on every page, the totals and page numbers, ready to send. The CSV starts with the column labels and neutralizes a text cell that a spreadsheet would run as a formula.
screenrig reports show fleet_health --group-by folder --format pdf --output fleet-health.pdf
screenrig reports show proof_of_play --advertiser "Acme Corp" --from 2026-10-01 --to 2026-10-31 --format pdf --output acme.pdf
screenrig project uptime --format xlsx --output uptime.xlsx
screenrig alerts list --state all --format csv --output alerts.csv
Proof of play for a sponsor or an advertiser
proof_of_play totals the plays of the project's direct campaigns. A play counts when the screen reports the media completed on glass. Name one campaign with campaign_id, or every campaign of a sponsor or advertiser with advertiser (its exact name, any case). Each row is a campaign, a media file and a screen with its plays, played hours, first and last day and, when the screen carries an audience estimate, estimated impressions. The PDF is the statement to send.
Email schedules
A report subscription names a report kind and its filters, a cadence, a file format and the project members it goes to. POST /api/report-subscriptions creates one; an organization has at most 50 across its projects (report_subscription_limit_reached).
| Member | Meaning |
|---|---|
name | 1 to 100 characters |
kind | fleet_health, uptime, publishing, alerts, alert_log or proof_of_play |
filters | The report's filters other than the days: group_by, folder_id, direct, tag, campaign_id, advertiser |
schedule | cadence daily, weekly (weekday, default monday) or monthly (day_of_month, 1 to 28, default 1), hour 0 to 23 and an IANA timezone (default UTC) |
format | pdf, xlsx or csv, attached to the email |
recipients | Up to 25 project members, by user_id, by the email address of the member or as owner |
enabled | false pauses the subscription; the default is true |
Each run covers the period before it in UTC days: the day before a daily run, the seven days before a weekly run and the whole month before a monthly run, counted on the calendar of the schedule's time zone. Recipients are members of the project, checked again at every send: anyone else is refused when the subscription is written, and a member who leaves, or whose address is not verified, stops receiving it. The attachment is at most 8 MiB.
A failed run is retried after 15 minutes, 1 hour and 4 hours and then waits for the next occurrence. The subscription shows last_status (delivered or failed), last_error, the days the last run covered and next_run_at. POST /api/report-subscriptions/{id}/send sends it now for the period a run now would cover, without moving its schedule, and answers with the subscription and this send's outcome.
screenrig reports subscriptions create --name "Monday fleet health" --kind fleet_health \
--cadence weekly --weekday monday --hour 7 --timezone America/Los_Angeles \
--format pdf --recipients ann@example.com,usr_ID
screenrig reports subscriptions list
screenrig reports subscriptions send rsub_ID
screenrig reports subscriptions update rsub_ID --pause
--filter NAME=VALUE, repeatable, sets a report filter such as group_by=screen. update changes a subscription, and --pause and --resume stop and restart it. A subscription keeps its report kind: create another to send a different report. show reads one and delete removes it.
The Email schedules tab of the dashboard's Screen reports page has the same schedules, with Send now, Pause and Resume.
Export a whole project
screenrig project export DIR writes project data to a directory in open formats. Inspect each section's outcome before using the copy for recovery: data.complete is false when a section failed, and a section the credential or the plan does not reach is reported as skipped.
| Path | Holds |
|---|---|
export.json | The format (screenrig.export/v1), when it was made, every section's outcome and every file with its size and SHA-256 |
project.json, tags.json | The project and its tags with their screens |
screens/ | screens.json, folders.json and schedules.json (each screen's levels, takeover and display schedule) |
playlists/ | Each playlist and every revision, as JSON |
campaigns.json, advertising/direct-campaigns.json | Campaigns and direct campaigns |
cards/, sources.json, applications.json, triggers.json | Cards with their data, data source configuration, application metadata and alert triggers |
applications/APP_ID/kv.json | Each application's persistent K/V entries: base64 values, content types, byte counts, SHA-256 and revisions |
notifications.json, webhooks.json, alert-mutes.json, report-subscriptions.json | Notifications, webhooks, mutes and schedules |
media/files/, media/manifest.json, media/media.json and media/folders.json | The original media files, each file's id, name, type, size and SHA-256, the media records and the media folders |
data/ | CSV for plays, plays by day, screen and media, daily uptime, uptime by screen and alerts |
log/events.jsonl | The project event log, one JSON event per line |
log/audit.jsonl, log/audit-head.json | The audit log, one JSON entry per line, and its chain head |
Keep the original application archives alongside exports for release recovery, including older playlist pins. Application content omissions appear in the application files section and set data.complete:false with export_application_content_omitted, including with --no-media. Rerunning refreshes metadata.
Application K/V is copied in full with both --no-media and --since. A failed K/V list or value read fails the applications section with export_section_failed and sets data.complete:false. Resolve the read error and rerun to refresh the copy.
Credentials are never in the copy: a webhook's signing secret and receiver address, a notification's chat or pager credential and a data source's secrets are left out (the file keeps the receiver's origin and the names of the secrets). A rerun is safe: JSON files are rewritten whole, a media file that is already complete is kept, and a partly downloaded one continues from the bytes it has. Each media file is checked against the SHA-256 the project holds before it is kept. --no-media skips the media files and --since DAY starts the CSV data, the event log and the audit log on a day. Every request is a billed API request, and media downloads are egress.