API reference
Uptime
Uptime is how much of its counted time a screen was up. It is reported for all screens, for one site or for one screen, with a total and a trend a day at a time. See Monitoring for the guide.
The Uptime object
Uptime for a group of screens over a period: the total, a day-by-day trend, and each screen’s own figures.
Attributes
fromstring (date)Optionaltostring (date)OptionalsitestringOptionalThe site code; only on a site’s answer.
totalsobjectOptionalShow child attributesHide child attributes
countedSinteger (int64)OptionalSeconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
downSinteger (int64)OptionalCounted seconds the screen was not showing what it should (down, a gap, a power cut, a restart, a crash, time Mestra heard nothing from it and it sent no record for, and disputed minutes).
sitePowerSinteger (int64)OptionalCounted seconds lost to the site’s power.
holdingSinteger (int64)OptionalCounted seconds the panel showed the stop show from its own storage while it restarted. They count against uptime (they are in
downS) and are reported here on their own.standbySinteger (int64)OptionalCounted seconds the standby player showed a live item. They count as up. A standby showing the stop show because its information is stale counts as down.
silentSinteger (int64)OptionalCounted seconds Mestra heard nothing from the screen and it sent no record for (it was off longer than its own record fills, or never came back). Mestra’s own record, not the screen’s; they are in
downS. Time the screen later sends signed hours for is never counted here: Mestra’s own outages do not count against a screen.disputedMinutesinteger (int64)OptionalMinutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
lateMinutesinteger (int64)OptionalMinutes that arrived more than two hours after their hour ended: the screen’s own report of time it was offline, reported apart, and no longer a dispute.
offlineUnverifiedSinteger (int64)OptionalCounted seconds of content the screen claimed while Mestra heard nothing from it (the network between them was down, however long). They count as up, resting on the screen’s own signed record, and are reported apart so they can be checked; they are in the up time, not in downS.
uptimenumberOptionalNullable(countedS - downS) / countedS; null when nothing was counted.
uptimeExSitePowernumberOptionalNullable(countedS - downS) / (countedS - sitePowerS).
trendobjectOptionalUptime a day at a time: 30 days, oldest first, each the up seconds over the counted seconds of that day, cut (never rounded up) to four places; null where nothing was counted. On a screen in a paged list, on a site in the list of sites, and on an uptime answer for the default span.
Show child attributesHide child attributes
tostring (date)OptionalThe last of the 30 days.
daysarray of numbersOptional
screensarray of objectsOptionalShow child attributesHide child attributes
countedSinteger (int64)OptionalSeconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
downSinteger (int64)OptionalCounted seconds the screen was not showing what it should (down, a gap, a power cut, a restart, a crash, time Mestra heard nothing from it and it sent no record for, and disputed minutes).
sitePowerSinteger (int64)OptionalCounted seconds lost to the site’s power.
holdingSinteger (int64)OptionalCounted seconds the panel showed the stop show from its own storage while it restarted. They count against uptime (they are in
downS) and are reported here on their own.standbySinteger (int64)OptionalCounted seconds the standby player showed a live item. They count as up. A standby showing the stop show because its information is stale counts as down.
silentSinteger (int64)OptionalCounted seconds Mestra heard nothing from the screen and it sent no record for (it was off longer than its own record fills, or never came back). Mestra’s own record, not the screen’s; they are in
downS. Time the screen later sends signed hours for is never counted here: Mestra’s own outages do not count against a screen.disputedMinutesinteger (int64)OptionalMinutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
lateMinutesinteger (int64)OptionalMinutes that arrived more than two hours after their hour ended: the screen’s own report of time it was offline, reported apart, and no longer a dispute.
offlineUnverifiedSinteger (int64)OptionalCounted seconds of content the screen claimed while Mestra heard nothing from it (the network between them was down, however long). They count as up, resting on the screen’s own signed record, and are reported apart so they can be checked; they are in the up time, not in downS.
uptimenumberOptionalNullable(countedS - downS) / countedS; null when nothing was counted.
uptimeExSitePowernumberOptionalNullable(countedS - downS) / (countedS - sitePowerS).
idstring (uuid)OptionalnamestringOptional
Retrieve a screen's uptime
Any member’s session (viewer, editor or owner), or a key with the Screens permission. The screen’s days in its own zone, each with the seconds counted, the seconds down, the seconds lost to the site’s power, and Mestra’s signed statement of the day (receipt; how to check it is in the guide Verify plays, batches and uptime). A day appears two hours after it closed, once Mestra’s own record of the screen being silent is settled, whether or not the screen sent its hours (a screen that is off counts as down, silentS); a screen that was offline sends its hours later and the day is signed again with a higher revision. uptime is up over counted seconds; uptimeExSitePower leaves the seconds lost to the site’s power out of both. disputedMinutes are minutes whose record contradicts what Mestra held (the screen reported content while it was stopped, or the hour’s record was rewritten); a disputed minute is never up, so it is in countedS and downS, and the count says how many to check. totals add the days’ seconds before dividing.
Path parameters
idstring (uuid)Required
Query parameters
fromstring (date)OptionalFirst day, in the screen’s own zone, inclusive. Default: 29 days before
to.tostring (date)OptionalLast day, inclusive. Default: today (UTC).
Returns
The days and their totals.
An object with:
screenIdstring (uuid)Optionalfromstring (date)Optionaltostring (date)Optionaldaysarray of objectsOptionalShow child attributesHide child attributes
countedSinteger (int64)OptionalSeconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
downSinteger (int64)OptionalCounted seconds the screen was not showing what it should (down, a gap, a power cut, a restart, a crash, time Mestra heard nothing from it and it sent no record for, and disputed minutes).
sitePowerSinteger (int64)OptionalCounted seconds lost to the site’s power.
holdingSinteger (int64)OptionalCounted seconds the panel showed the stop show from its own storage while it restarted. They count against uptime (they are in
downS) and are reported here on their own.standbySinteger (int64)OptionalCounted seconds the standby player showed a live item. They count as up. A standby showing the stop show because its information is stale counts as down.
silentSinteger (int64)OptionalCounted seconds Mestra heard nothing from the screen and it sent no record for (it was off longer than its own record fills, or never came back). Mestra’s own record, not the screen’s; they are in
downS. Time the screen later sends signed hours for is never counted here: Mestra’s own outages do not count against a screen.disputedMinutesinteger (int64)OptionalMinutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
lateMinutesinteger (int64)OptionalMinutes that arrived more than two hours after their hour ended: the screen’s own report of time it was offline, reported apart, and no longer a dispute.
offlineUnverifiedSinteger (int64)OptionalCounted seconds of content the screen claimed while Mestra heard nothing from it (the network between them was down, however long). They count as up, resting on the screen’s own signed record, and are reported apart so they can be checked; they are in the up time, not in downS.
uptimenumberOptionalNullable(countedS - downS) / countedS; null when nothing was counted.
uptimeExSitePowernumberOptionalNullable(countedS - downS) / (countedS - sitePowerS).
daystring (date)OptionalThe day in the screen’s own zone.
revisionintegerOptionalHow many times the day was rolled with new input. The statement carries the same number; an older statement of the day has a lower one.
byCauseobjectOptionalSeconds counted against uptime, by
down,gap,site_power,restart,crash,holding,silent(Mestra heard nothing and the screen sent no record) ordisputed.signedBystringOptionalWhich device key signed the hours the day rests on:
tpmwhen every hour that gave the day a minute was signed with a key made in the screen’s TPM and proven by it,softwarewhen all were signed but not all by a TPM key. Absent when an hour was not signed (it was sent before the screen had a key, or the screen had been proven a copy). The signed statement carries the same member, only when present.Possible values
tpmsoftwarereceiptobjectOptionalNullableMestra’s signed statement of the day, signed with the receipt keys under the domain
mestra-uptime-v1.
totalsobjectOptionalShow child attributesHide child attributes
countedSinteger (int64)OptionalSeconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
downSinteger (int64)OptionalCounted seconds the screen was not showing what it should (down, a gap, a power cut, a restart, a crash, time Mestra heard nothing from it and it sent no record for, and disputed minutes).
sitePowerSinteger (int64)OptionalCounted seconds lost to the site’s power.
holdingSinteger (int64)OptionalCounted seconds the panel showed the stop show from its own storage while it restarted. They count against uptime (they are in
downS) and are reported here on their own.standbySinteger (int64)OptionalCounted seconds the standby player showed a live item. They count as up. A standby showing the stop show because its information is stale counts as down.
silentSinteger (int64)OptionalCounted seconds Mestra heard nothing from the screen and it sent no record for (it was off longer than its own record fills, or never came back). Mestra’s own record, not the screen’s; they are in
downS. Time the screen later sends signed hours for is never counted here: Mestra’s own outages do not count against a screen.disputedMinutesinteger (int64)OptionalMinutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
lateMinutesinteger (int64)OptionalMinutes that arrived more than two hours after their hour ended: the screen’s own report of time it was offline, reported apart, and no longer a dispute.
offlineUnverifiedSinteger (int64)OptionalCounted seconds of content the screen claimed while Mestra heard nothing from it (the network between them was down, however long). They count as up, resting on the screen’s own signed record, and are reported apart so they can be checked; they are in the up time, not in downS.
uptimenumberOptionalNullable(countedS - downS) / countedS; null when nothing was counted.
uptimeExSitePowernumberOptionalNullable(countedS - downS) / (countedS - sitePowerS).
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_screennot_connected |
|
409 | api_offintegration_off |
|
422 |
| |
501 | The player is not available on this server. |
Retrieve a site's uptime
Any member’s session (viewer, editor or owner), or a key with the Screens permission. The seconds of every screen linked to the site, added up, and each screen’s own. A total is always the sum of up seconds over the sum of counted seconds, never an average of the screens’ percentages. A key limited to some screens counts only those.
Path parameters
sitestringRequiredThe brand code.
Query parameters
fromstring (date)OptionalFirst day, in the screen’s own zone, inclusive. Default: 29 days before
to.tostring (date)OptionalLast day, inclusive. Default: today (UTC).
Returns
The site’s totals and its screens’.
Returns the Uptime object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_sitenot_connected |
|
409 | api_offintegration_off |
|
422 |
| |
501 | The player is not available on this server. |
Retrieve uptime
Any member’s session (viewer, editor or owner), or a key with the Screens permission. The seconds of every screen in your scope, added up, and each screen’s own. A total is always the sum of up seconds over the sum of counted seconds, never an average of percentages.
Query parameters
fromstring (date)OptionalFirst day, in the screen’s own zone, inclusive. Default: 29 days before
to.tostring (date)OptionalLast day, inclusive. Default: today (UTC).
Returns
The totals and each screen’s.
Returns the Uptime object.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connected |
|
409 | api_offintegration_off |
|
422 |
| |
501 | The player is not available on this server. |