# Plays

A play is the proof that a screen showed a booked item at a time. Plays are listed, totalled and exported as CSV, and a batch is the set of plays a screen uploaded together, signed by Mestra. To check a proof-of-play row or a play batch against Mestra's public keys, see [Verify plays, batches and uptime](https://withmestra.com/docs/player/api/verify/). See [Proof of play](https://withmestra.com/docs/player/proof-of-play/) for the guide.

A play is the proof that a screen showed a booked item at a time. Plays are listed, totalled and exported as CSV, and a batch is the set of plays a screen uploaded together, signed by Mestra. To check a proof-of-play row or a play batch against Mestra's public keys, see [Verify plays, batches and uptime](https://withmestra.com/docs/player/api/verify/). See [Proof of play](https://withmestra.com/docs/player/proof-of-play/) for the guide.

## The Play object

One play: a screen showing a booked item at a moment, with the screen, site, booking and length, and a hash and check that tie it to Mestra's signed receipt.

- `id` (string, optional): A stable id for the play.
- `source` (string, optional):  One of: `mestra`.
- `playedBy` (string, optional): Which player showed the play: `standby` when the screen's backup player showed any part of it while the main player was being repaired, else `main`. Plays stored before this existed read `main`. `source` is the kind of screen, not this. One of: `main`, `standby`.
- `screenId` (string (uuid), optional):
- `screenName` (string, optional): Empty when the screen has been removed.
- `frame` (object, optional, nullable): The frame of the screen the play was in; null for a play of the whole window.
  - `id` (string (uuid), optional):
  - `name` (string, optional):
- `site` (object, optional, nullable): The site the screen was linked to when it played, the same `{key, name}` a screen's `site` has; null when it had none. Plays stored before this was recorded show the screen's current link.
  - `key` (string, optional): The brand code.
  - `name` (string, optional):
- `batch` (object, optional, nullable): The signed batch of plays this play arrived in; read it with `GET /player/plays/batches/{id}`. Null for a play stored before batches.
  - `id` (string (uuid), required):
- `publicationId` (string (uuid), optional):
- `itemId` (string (uuid), optional):
- `entryId` (string (uuid), optional):
- `playedAtLocal` (string, optional): The play's start on the screen's own clock, `YYYY-MM-DDTHH:MM:SS.mmm`.
- `outOfStep` (boolean, optional): True when a member of a group played this item out of step: it was in step for less than the in-step floor (95%) of its slot. The play is kept and listed, never counted in totals or the CSV. Absent when false.
- `inStepPct` (integer, optional): For a group item's play: the share of the slot the member was in step, in percent. Absent for a single screen's play.
- `stepP95Ms` (integer, optional): For a group item's play: the 95th percentile of the member's offset from the group's step, in milliseconds. Absent for a single screen's play.
- `zone` (string, optional): The screen's time zone.
- `playedAt` (string (date-time), optional): The start as a UTC time.
- `durationMs` (integer, optional):
- `sha256` (string, optional):
- `check` (object, optional):
  - `state` (string, optional):  One of: `signed`, `checked`, `unchecked`.
  - `renderCheckId` (string (uuid), optional, nullable):
  - `receipt` (object, optional, nullable): The signed receipt when `state` is `signed`, else null.

```json
{
  "id": "string",
  "source": "mestra",
  "playedBy": "main",
  "screenId": "string",
  "screenName": "string",
  "publicationId": "string",
  "itemId": "string",
  "entryId": "string",
  "playedAtLocal": "string",
  "outOfStep": false,
  "inStepPct": 0,
  "stepP95Ms": 0,
  "zone": "string",
  "playedAt": "string",
  "durationMs": 0,
  "sha256": "string",
  "check": {
    "state": "signed",
    "renderCheckId": "string",
    "receipt": {}
  }
}
```

## List all plays

`GET /api/v1/player/plays`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. The proof of play of your Mestra Player screens, in the order Mestra stored them. Every play has `source` `mestra`. A play shows a minute after Mestra stores it. `check.state` is `signed` (the file passed its checks and has a signed receipt, which is included), `checked` (it passed, no receipt) or `unchecked`. A page holds up to `limit` plays. `next` is the cursor to resume from: that of the page's last play, or, when the page is empty, the `cursor` you sent. `more` is true while another page is ready now. To follow the feed, keep the last `next` and ask again with it later: a play that a screen uploaded late then appears after it. `next` is null only when you sent no cursor and there are no plays yet. A play never moves between pages, so reading with the cursor sees each play once. A screen that has since been removed keeps its plays.

### Parameters

- `cursor` (string, optional): The `next` of the previous response. Leave it out to start from the oldest play.
- `limit` (integer, optional): Plays in the page, 1 to 1000.
- `screen` (string (uuid), optional): Only this screen's plays, or a frame's when a frame id is given. A group id gives the plays of the group: those recorded under the group (a screen that has since left the group keeps them in it), and, for a play whose record carries no group (a screen's own booking, or one stored before records carried it), those of the group's members now. A key limited to a group may name the group or any of its members.
- `site` (string, optional): Only the plays at this site code: the site the screen was linked to when it played. A play stored before that was recorded, or while the screen had no link, counts at the screen's current link.
- `publication` (string (uuid), optional): Only this publication's plays.
- `rowId` (string, optional): Only the plays that showed this row of a Dynamic booking's table (the row id the table names it by). A play of an ordinary booking has no row.
- `customer` (string (uuid), optional): Only the plays of this customer's bookings. A play names no customer: its booking does, read when you ask, so a booking moved to another customer takes its plays with it. A customer that isn't yours is 404 `unknown_customer`.
- `playedFrom` (string (date), optional): First day, on the screen's own clock, inclusive.
- `playedTo` (string (date), optional): Last day, on the screen's own clock, inclusive.

### Returns

A page of plays.

An object with:

- `plays` (array of objects, optional):
  - `id` (string, optional): A stable id for the play.
  - `source` (string, optional):  One of: `mestra`.
  - `playedBy` (string, optional): Which player showed the play: `standby` when the screen's backup player showed any part of it while the main player was being repaired, else `main`. Plays stored before this existed read `main`. `source` is the kind of screen, not this. One of: `main`, `standby`.
  - `screenId` (string (uuid), optional):
  - `screenName` (string, optional): Empty when the screen has been removed.
  - `frame` (object, optional, nullable): The frame of the screen the play was in; null for a play of the whole window.
    - `id` (string (uuid), optional):
    - `name` (string, optional):
  - `site` (object, optional, nullable): The site the screen was linked to when it played, the same `{key, name}` a screen's `site` has; null when it had none. Plays stored before this was recorded show the screen's current link.
    - `key` (string, optional): The brand code.
    - `name` (string, optional):
  - `batch` (object, optional, nullable): The signed batch of plays this play arrived in; read it with `GET /player/plays/batches/{id}`. Null for a play stored before batches.
    - `id` (string (uuid), required):
  - `publicationId` (string (uuid), optional):
  - `itemId` (string (uuid), optional):
  - `entryId` (string (uuid), optional):
  - `playedAtLocal` (string, optional): The play's start on the screen's own clock, `YYYY-MM-DDTHH:MM:SS.mmm`.
  - `outOfStep` (boolean, optional): True when a member of a group played this item out of step: it was in step for less than the in-step floor (95%) of its slot. The play is kept and listed, never counted in totals or the CSV. Absent when false.
  - `inStepPct` (integer, optional): For a group item's play: the share of the slot the member was in step, in percent. Absent for a single screen's play.
  - `stepP95Ms` (integer, optional): For a group item's play: the 95th percentile of the member's offset from the group's step, in milliseconds. Absent for a single screen's play.
  - `zone` (string, optional): The screen's time zone.
  - `playedAt` (string (date-time), optional): The start as a UTC time.
  - `durationMs` (integer, optional):
  - `sha256` (string, optional):
  - `check` (object, optional):
    - `state` (string, optional):  One of: `signed`, `checked`, `unchecked`.
    - `renderCheckId` (string (uuid), optional, nullable):
    - `receipt` (object, optional, nullable): The signed receipt when `state` is `signed`, else null.
- `next` (string, optional, nullable): The cursor to resume from: the last play's, or the one you sent when the page is empty. Null only when you sent none and there are no plays.
- `more` (boolean, optional): True while another page is ready now; false on the last. Ask again later with `next` to follow the feed.

### Errors

- 400: A bad `cursor`, a `limit` outside 1 to 1000, a bad date, or a bad id (`field` names it).
- 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`, `unknown_screen`, `unknown_customer`, `unknown_site`): `not_connected`, `unknown_screen` (with `?screen=`), `unknown_customer` (with `?customer=`), or `unknown_site` (with `?site=`, only for a key limited to some screens and none of them linked to that site; a key for every screen gets an empty list).
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

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

## Retrieve play totals

`GET /api/v1/player/plays/summary`

Permission: Screens · Read.

Any member's session (viewer, editor or owner), or a key with the Screens permission. Counts the plays the list returns over the same filters, except those a group member played out of step (`outOfStep` true in the list): they stay in the record and are never counted here or in the CSV. Rows are by publication, screen, site, customer or day, in key order. A play counts at the site it was linked to when it played, so moving a screen to another centre leaves its earlier plays where they were. Each row has the plays, their airtime in milliseconds, the screens that played, and how many plays are `signed`, `checked` and `unchecked`.

### Parameters

- `groupBy` (string, required): What to count by. `day` is the screen's own date. `customer` is the customer of the booking now, named as it is named now; plays of a booking with no customer are `key` empty, `label` "No customer". One of: `publication`, `screen`, `site`, `customer`, `day`.
- `screen` (string (uuid), optional): Only this screen's plays. A group id gives the plays of the group: those recorded under the group (a screen that has since left the group keeps them in it), and, for a play whose record carries no group (a screen's own booking, or one stored before records carried it), those of the group's members now. A key limited to a group may name the group or any of its members.
- `site` (string, optional): Only the plays at this site code: the site the screen was linked to when it played. A play stored before that was recorded, or while the screen had no link, counts at the screen's current link.
- `publication` (string (uuid), optional): Only this publication's plays.
- `rowId` (string, optional): Only the plays that showed this row of a Dynamic booking's table (the row id the table names it by). A play of an ordinary booking has no row.
- `customer` (string (uuid), optional): Only the plays of this customer's bookings. A play names no customer: its booking does, read when you ask, so a booking moved to another customer takes its plays with it. A customer that isn't yours is 404 `unknown_customer`.
- `playedFrom` (string (date), optional): First day, on the screen's own clock, inclusive.
- `playedTo` (string (date), optional): Last day, on the screen's own clock, inclusive.

### Returns

The totals.

An object with:

- `groupBy` (string, optional):  One of: `publication`, `screen`, `site`, `customer`, `day`.
- `rows` (array of objects, optional):
  - `key` (string, optional): The group: a publication id, a screen id, a site code (empty for no site) or a date.
  - `label` (string, optional): The publication's campaign key, the screen's name, the site code, or the date.
  - `plays` (integer, optional):
  - `durationMs` (integer, optional):
  - `screens` (integer, optional): Screens that played.
  - `signed` (integer, optional): Plays whose file's check has a signed receipt stored. In the rare case a stored receipt can't be read back, the play itself shows `checked`, so this can be more than the `signed` plays the feed and export show.
  - `checked` (integer, optional): Plays whose file passed a check with no signed receipt stored.
  - `unchecked` (integer, optional): Plays whose file had no check.

### Errors

- 400: A missing or unknown `groupBy`, a bad date, or a bad id (`field` names it).
- 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`, `unknown_screen`, `unknown_customer`, `unknown_site`): `not_connected`, `unknown_screen` (with `?screen=`), `unknown_customer` (with `?customer=`), or `unknown_site` (with `?site=`, only for a key limited to some screens and none of them linked to that site; a key for every screen gets an empty list).
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

```sh
curl --request GET \
  --url 'https://app.withmestra.com/api/v1/player/plays/summary?groupBy=publication' \
  --header "Authorization: Bearer $MESTRA_TOKEN"
```

## Download plays as CSV

`GET /api/v1/player/plays.csv`

Permission: Screens · Read.

Needs an editor's or an owner's key or session. Every play the filters match except those a group member played out of step (`outOfStep` true in the list), as a CSV download with no page limit. The header row is (the order is fixed; columns are only ever added at the end) `play_id,screen_id,screen_name,site_key,site_name,publication_id,item_id,entry_id,played_at_local,zone,played_at_utc,duration_ms,sha256,played_by,check_state,render_check_id,receipt_key_id,receipt_json,batch_id,customer,row`. `site_key` and `site_name` are the two parts of the JSON `site` object, both empty when the play has no site. `batch_id` is the JSON `batch.id`, empty for a play stored before batches. `customer` is the name of the customer its booking is for now, empty when it has none. `row` is the id of the row of a Dynamic booking's table that the play showed (the value the `rowId` filter takes), empty for an ordinary booking. A cell that starts with `=`, `+`, `-`, `@`, a tab or a carriage return begins with `'` so a spreadsheet won't run it. The export is the plays stored a minute or more before it started. It streams: if it fails part-way the connection is cut without a clean end, so treat a download that ends in an error as incomplete.

### Parameters

- `screen` (string (uuid), optional): Only this screen's plays. A group id gives the plays of the group: those recorded under the group (a screen that has since left the group keeps them in it), and, for a play whose record carries no group (a screen's own booking, or one stored before records carried it), those of the group's members now. A key limited to a group may name the group or any of its members.
- `site` (string, optional): Only the plays at this site code: the site the screen was linked to when it played. A play stored before that was recorded, or while the screen had no link, counts at the screen's current link.
- `publication` (string (uuid), optional): Only this publication's plays.
- `rowId` (string, optional): Only the plays that showed this row of a Dynamic booking's table (the row id the table names it by). A play of an ordinary booking has no row.
- `customer` (string (uuid), optional): Only the plays of this customer's bookings. A play names no customer: its booking does, read when you ask, so a booking moved to another customer takes its plays with it. A customer that isn't yours is 404 `unknown_customer`.
- `playedFrom` (string (date), optional): First day, on the screen's own clock, inclusive.
- `playedTo` (string (date), optional): Last day, on the screen's own clock, inclusive.

### Returns

The plays, as CSV.

### Errors

- 400: A bad date or id (`field` names it).
- 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. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`not_connected`, `unknown_screen`, `unknown_customer`, `unknown_site`): `not_connected`, `unknown_screen` (with `?screen=`), `unknown_customer` (with `?customer=`), or `unknown_site` (with `?site=`, only for a key limited to some screens and none of them linked to that site; a key for every screen gets an empty list).
- 409 (`api_off`, `integration_off`): `api_off` (an owner hasn't turned the API on), or `integration_off` (Mestra screens are off).
- 501: The player is not available on this server.

### Example request

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

## Retrieve a signed batch of plays

`GET /api/v1/player/plays/batches/{id}`

Permission: Screens · Read.

Needs an editor's or an owner's key or session. A batch is one upload of plays from one screen, as Mestra stored it, with the receipt Mestra signed as it arrived. Each play in the list carries `batch.id`. `plays` are the batch's own plays (at most 500), exactly as the plays list shows them. A third party checks the batch with only this response and the public keys at `/.well-known/mestra-receipt-keys.json`: see the guide [Verify plays, batches and uptime](https://withmestra.com/docs/player/api/verify/). The receipt says Mestra received exactly these plays from this screen at this time, and has not changed them since. It does not prove that anyone saw the content, or that the screen's report is true. `signed` is false, and `receipt` null, for a batch stored while the server had no signing key. A batch shows once its plays do (a minute after Mestra stores them).

### Parameters

- `id` (string (uuid), required):

### Returns

The batch and its plays.

An object with:

- `batch` (object, required):
  - `id` (string (uuid), required):
  - `screenId` (string (uuid), required):
  - `receivedAt` (string (date-time), required): When Mestra received the upload, to the microsecond.
  - `plays` (integer, required): How many plays the batch holds; the length of `plays`.
  - `signed` (boolean, required):
  - `receipt` (object, required, nullable): Mestra's signature over the batch: `version`, `keyId`, `orgId`, `screenId`, `batchId`, `receivedAt`, `plays`, `playsDigest`, `createdAt` and `signature`. Null when `signed` is false.
- `plays` (array of objects, required):
  - `id` (string, optional): A stable id for the play.
  - `source` (string, optional):  One of: `mestra`.
  - `playedBy` (string, optional): Which player showed the play: `standby` when the screen's backup player showed any part of it while the main player was being repaired, else `main`. Plays stored before this existed read `main`. `source` is the kind of screen, not this. One of: `main`, `standby`.
  - `screenId` (string (uuid), optional):
  - `screenName` (string, optional): Empty when the screen has been removed.
  - `frame` (object, optional, nullable): The frame of the screen the play was in; null for a play of the whole window.
    - `id` (string (uuid), optional):
    - `name` (string, optional):
  - `site` (object, optional, nullable): The site the screen was linked to when it played, the same `{key, name}` a screen's `site` has; null when it had none. Plays stored before this was recorded show the screen's current link.
    - `key` (string, optional): The brand code.
    - `name` (string, optional):
  - `batch` (object, optional, nullable): The signed batch of plays this play arrived in; read it with `GET /player/plays/batches/{id}`. Null for a play stored before batches.
    - `id` (string (uuid), required):
  - `publicationId` (string (uuid), optional):
  - `itemId` (string (uuid), optional):
  - `entryId` (string (uuid), optional):
  - `playedAtLocal` (string, optional): The play's start on the screen's own clock, `YYYY-MM-DDTHH:MM:SS.mmm`.
  - `outOfStep` (boolean, optional): True when a member of a group played this item out of step: it was in step for less than the in-step floor (95%) of its slot. The play is kept and listed, never counted in totals or the CSV. Absent when false.
  - `inStepPct` (integer, optional): For a group item's play: the share of the slot the member was in step, in percent. Absent for a single screen's play.
  - `stepP95Ms` (integer, optional): For a group item's play: the 95th percentile of the member's offset from the group's step, in milliseconds. Absent for a single screen's play.
  - `zone` (string, optional): The screen's time zone.
  - `playedAt` (string (date-time), optional): The start as a UTC time.
  - `durationMs` (integer, optional):
  - `sha256` (string, optional):
  - `check` (object, optional):
    - `state` (string, optional):  One of: `signed`, `checked`, `unchecked`.
    - `renderCheckId` (string (uuid), optional, nullable):
    - `receipt` (object, optional, nullable): The signed receipt when `state` is `signed`, else null.

### 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. A session below an editor's gets “Your role (\<role>) can't \<action>.”
- 404 (`unknown_batch`, `batch_incomplete`, `not_connected`): `unknown_batch`: no such batch, another organisation's, a screen outside a limited key's scope, or its plays are not shown yet. `batch_incomplete`: some of its plays were deleted afterwards with their booking, so it can't be rebuilt (not tampering). 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).
- 501: The player is not available on this server.

### Example request

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