Skip to content

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)Optional
  • tostring (date)Optional
  • sitestringOptional

    The site code; only on a site’s answer.

  • totalsobjectOptional
    Show child attributesHide child attributes
    • countedSinteger (int64)Optional

      Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.

    • downSinteger (int64)Optional

      Counted 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)Optional

      Counted seconds lost to the site’s power.

    • holdingSinteger (int64)Optional

      Counted 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)Optional

      Counted 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)Optional

      Counted 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)Optional

      Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.

    • lateMinutesinteger (int64)Optional

      Minutes 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)Optional

      Counted 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).

  • trendobjectOptional

    Uptime 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)Optional

      The last of the 30 days.

    • daysarray of numbersOptional
  • screensarray of objectsOptional
    Show child attributesHide child attributes
    • countedSinteger (int64)Optional

      Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.

    • downSinteger (int64)Optional

      Counted 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)Optional

      Counted seconds lost to the site’s power.

    • holdingSinteger (int64)Optional

      Counted 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)Optional

      Counted 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)Optional

      Counted 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)Optional

      Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.

    • lateMinutesinteger (int64)Optional

      Minutes 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)Optional

      Counted 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)Optional
    • namestringOptional

Retrieve a screen's uptime

PermissionScreens · Read

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)Optional

    First day, in the screen’s own zone, inclusive. Default: 29 days before to.

  • tostring (date)Optional

    Last day, inclusive. Default: today (UTC).

Returns

The days and their totals.

An object with:

  • screenIdstring (uuid)Optional
  • fromstring (date)Optional
  • tostring (date)Optional
  • daysarray of objectsOptional
    Show child attributesHide child attributes
    • countedSinteger (int64)Optional

      Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.

    • downSinteger (int64)Optional

      Counted 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)Optional

      Counted seconds lost to the site’s power.

    • holdingSinteger (int64)Optional

      Counted 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)Optional

      Counted 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)Optional

      Counted 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)Optional

      Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.

    • lateMinutesinteger (int64)Optional

      Minutes 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)Optional

      Counted 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)Optional

      The day in the screen’s own zone.

    • revisionintegerOptional

      How 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.

    • byCauseobjectOptional

      Seconds counted against uptime, by down, gap, site_power, restart, crash, holding, silent (Mestra heard nothing and the screen sent no record) or disputed.

    • signedBystringOptional

      Which device key signed the hours the day rests on: tpm when every hour that gave the day a minute was signed with a key made in the screen’s TPM and proven by it, software when 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 valuestpmsoftware

    • receiptobjectOptionalNullable

      Mestra’s signed statement of the day, signed with the receipt keys under the domain mestra-uptime-v1.

  • totalsobjectOptional
    Show child attributesHide child attributes
    • countedSinteger (int64)Optional

      Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.

    • downSinteger (int64)Optional

      Counted 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)Optional

      Counted seconds lost to the site’s power.

    • holdingSinteger (int64)Optional

      Counted 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)Optional

      Counted 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)Optional

      Counted 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)Optional

      Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.

    • lateMinutesinteger (int64)Optional

      Minutes 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)Optional

      Counted 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

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens permission this call needs.

404unknown_screennot_connected

unknown_screen (no such screen, or one outside the key’s scope), or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are off).

422

from or to is not a date (YYYY-MM-DD), from is after to, or more than 366 days were asked for. field names it.

501

The player is not available on this server.

Retrieve a site's uptime

PermissionScreens · Read

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

  • sitestringRequired

    The brand code.

Query parameters

  • fromstring (date)Optional

    First day, in the screen’s own zone, inclusive. Default: 29 days before to.

  • tostring (date)Optional

    Last day, inclusive. Default: today (UTC).

Returns

The site’s totals and its screens’.

Returns the Uptime object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens permission this call needs.

404unknown_sitenot_connected

unknown_site (no screen in your scope is linked to that site), or not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are off).

422

from or to is not a date (YYYY-MM-DD), from is after to, or more than 366 days were asked for. field names it.

501

The player is not available on this server.

Retrieve uptime

PermissionScreens · Read

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)Optional

    First day, in the screen’s own zone, inclusive. Default: 29 days before to.

  • tostring (date)Optional

    Last day, inclusive. Default: today (UTC).

Returns

The totals and each screen’s.

Returns the Uptime object.

Errors

StatusCodeMeaning
401invalid_token

The key is missing, unknown, revoked or expired (code invalid_token). Send it as Authorization: Bearer <key>.

403wrong_key

wrong_key: the key lacks the Screens permission this call needs.

404not_connected

not_connected.

409api_offintegration_off

api_off (an owner hasn’t turned the API on), or integration_off (Mestra screens are off).

422

from or to is not a date (YYYY-MM-DD), from is after to, or more than 366 days were asked for. field names it.

501

The player is not available on this server.