# 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](https://withmestra.com/docs/player/monitoring/) for the guide.

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](https://withmestra.com/docs/player/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.

- `from` (string (date), optional):
- `to` (string (date), optional):
- `site` (string, optional): The site code; only on a site's answer.
- `totals` (object, optional):
  - `countedS` (integer (int64), optional): Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
  - `downS` (integer (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).
  - `sitePowerS` (integer (int64), optional): Counted seconds lost to the site's power.
  - `holdingS` (integer (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.
  - `standbyS` (integer (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.
  - `silentS` (integer (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.
  - `disputedMinutes` (integer (int64), optional): Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
  - `lateMinutes` (integer (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.
  - `offlineUnverifiedS` (integer (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.
  - `uptime` (number, optional, nullable): (countedS - downS) / countedS; null when nothing was counted.
  - `uptimeExSitePower` (number, optional, nullable): (countedS - downS) / (countedS - sitePowerS).
- `trend` (object, optional): 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.
  - `to` (string (date), optional): The last of the 30 days.
  - `days` (array of numbers, optional):
- `screens` (array of objects, optional):
  - `countedS` (integer (int64), optional): Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
  - `downS` (integer (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).
  - `sitePowerS` (integer (int64), optional): Counted seconds lost to the site's power.
  - `holdingS` (integer (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.
  - `standbyS` (integer (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.
  - `silentS` (integer (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.
  - `disputedMinutes` (integer (int64), optional): Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
  - `lateMinutes` (integer (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.
  - `offlineUnverifiedS` (integer (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.
  - `uptime` (number, optional, nullable): (countedS - downS) / countedS; null when nothing was counted.
  - `uptimeExSitePower` (number, optional, nullable): (countedS - downS) / (countedS - sitePowerS).
  - `id` (string (uuid), optional):
  - `name` (string, optional):

```json
{
  "from": "string",
  "to": "string",
  "site": "string",
  "totals": {
    "countedS": 0,
    "downS": 0,
    "sitePowerS": 0,
    "holdingS": 0,
    "standbyS": 0,
    "silentS": 0,
    "disputedMinutes": 0,
    "lateMinutes": 0,
    "offlineUnverifiedS": 0,
    "uptime": 0,
    "uptimeExSitePower": 0
  },
  "trend": {
    "to": "string",
    "days": [
      0
    ]
  },
  "screens": [
    {}
  ]
}
```

## Retrieve a screen's uptime

`GET /api/v1/player/devices/{id}/uptime`

Permission: Screens · 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](https://withmestra.com/docs/player/api/verify/)). 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.

### Parameters

- `id` (string (uuid), required):
- `from` (string (date), optional): First day, in the screen's own zone, inclusive. Default: 29 days before `to`.
- `to` (string (date), optional): Last day, inclusive. Default: today (UTC).

### Returns

The days and their totals.

An object with:

- `screenId` (string (uuid), optional):
- `from` (string (date), optional):
- `to` (string (date), optional):
- `days` (array of objects, optional):
  - `countedS` (integer (int64), optional): Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
  - `downS` (integer (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).
  - `sitePowerS` (integer (int64), optional): Counted seconds lost to the site's power.
  - `holdingS` (integer (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.
  - `standbyS` (integer (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.
  - `silentS` (integer (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.
  - `disputedMinutes` (integer (int64), optional): Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
  - `lateMinutes` (integer (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.
  - `offlineUnverifiedS` (integer (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.
  - `uptime` (number, optional, nullable): (countedS - downS) / countedS; null when nothing was counted.
  - `uptimeExSitePower` (number, optional, nullable): (countedS - downS) / (countedS - sitePowerS).
  - `day` (string (date), optional): The day in the screen's own zone.
  - `revision` (integer, optional): 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.
  - `byCause` (object, optional): Seconds counted against uptime, by `down`, `gap`, `site_power`, `restart`, `crash`, `holding`, `silent` (Mestra heard nothing and the screen sent no record) or `disputed`.
  - `signedBy` (string, optional): 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. One of: `tpm`, `software`.
  - `receipt` (object, optional, nullable): Mestra's signed statement of the day, signed with the receipt keys under the domain `mestra-uptime-v1`.
- `totals` (object, optional):
  - `countedS` (integer (int64), optional): Seconds that count: every second of the day except those the panel was off, the organisation halted, or the clock broke.
  - `downS` (integer (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).
  - `sitePowerS` (integer (int64), optional): Counted seconds lost to the site's power.
  - `holdingS` (integer (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.
  - `standbyS` (integer (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.
  - `silentS` (integer (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.
  - `disputedMinutes` (integer (int64), optional): Minutes whose record contradicts what Mestra held. They count as down (in countedS and downS); this says how many to check.
  - `lateMinutes` (integer (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.
  - `offlineUnverifiedS` (integer (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.
  - `uptime` (number, optional, nullable): (countedS - downS) / countedS; null when nothing was counted.
  - `uptimeExSitePower` (number, optional, nullable): (countedS - downS) / (countedS - sitePowerS).

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key`: the key lacks the Screens permission this call needs.
- 404 (`unknown_screen`, `not_connected`): `unknown_screen` (no such screen, or one outside the key's scope), or `not_connected`.
- 409 (`api_off`, `integration_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.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/devices/string/uptime \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve a site's uptime

`GET /api/v1/player/sites/{site}/uptime`

Permission: Screens · 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.

### Parameters

- `site` (string, required): The brand code.
- `from` (string (date), optional): First day, in the screen's own zone, inclusive. Default: 29 days before `to`.
- `to` (string (date), optional): Last day, inclusive. Default: today (UTC).

### Returns

The site's totals and its screens'.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key`: the key lacks the Screens permission this call needs.
- 404 (`unknown_site`, `not_connected`): `unknown_site` (no screen in your scope is linked to that site), or `not_connected`.
- 409 (`api_off`, `integration_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.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/sites/string/uptime \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Retrieve uptime

`GET /api/v1/player/uptime`

Permission: Screens · 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.

### Parameters

- `from` (string (date), optional): First day, in the screen's own zone, inclusive. Default: 29 days before `to`.
- `to` (string (date), optional): Last day, inclusive. Default: today (UTC).

### Returns

The totals and each screen's.

### Errors

- 401 (`invalid_token`): The key is missing, unknown, revoked or expired (code `invalid_token`). Send it as `Authorization: Bearer <key>`.
- 403 (`wrong_key`): `wrong_key`: the key lacks the Screens permission this call needs.
- 404 (`not_connected`): `not_connected`.
- 409 (`api_off`, `integration_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.

### Example request

```sh
curl --request GET \
  --url https://app.withmestra.com/api/v1/player/uptime \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```
