API reference
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. See 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.
Attributes
idstringOptionalA stable id for the play.
sourcestringOptionalPossible values
mestraplayedBystringOptionalWhich player showed the play:
standbywhen the screen’s backup player showed any part of it while the main player was being repaired, elsemain. Plays stored before this existed readmain.sourceis the kind of screen, not this.Possible values
mainstandbyscreenIdstring (uuid)OptionalscreenNamestringOptionalEmpty when the screen has been removed.
frameobjectOptionalNullableThe frame of the screen the play was in; null for a play of the whole window.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
siteobjectOptionalNullableThe site the screen was linked to when it played, the same
{key, name}a screen’ssitehas; null when it had none. Plays stored before this was recorded show the screen’s current link.Show child attributesHide child attributes
keystringOptionalThe brand code.
namestringOptional
batchobjectOptionalNullableThe signed batch of plays this play arrived in; read it with
GET /player/plays/batches/{id}. Null for a play stored before batches.Show child attributesHide child attributes
idstring (uuid)Required
publicationIdstring (uuid)OptionalitemIdstring (uuid)OptionalentryIdstring (uuid)OptionalplayedAtLocalstringOptionalThe play’s start on the screen’s own clock,
YYYY-MM-DDTHH:MM:SS.mmm.outOfStepbooleanOptionalTrue 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.
inStepPctintegerOptionalFor a group item’s play: the share of the slot the member was in step, in percent. Absent for a single screen’s play.
stepP95MsintegerOptionalFor 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.
zonestringOptionalThe screen’s time zone.
playedAtstring (date-time)OptionalThe start as a UTC time.
durationMsintegerOptionalsha256stringOptionalcheckobjectOptionalShow child attributesHide child attributes
statestringOptionalPossible values
signedcheckeduncheckedrenderCheckIdstring (uuid)OptionalNullablereceiptobjectOptionalNullableThe signed receipt when
stateissigned, else null.
List all plays
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.
Query parameters
cursorstringOptionalThe
nextof the previous response. Leave it out to start from the oldest play.limitintegerOptionalPlays in the page, 1 to 1000.
Default
200screenstring (uuid)OptionalOnly 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.
sitestringOptionalOnly 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.
publicationstring (uuid)OptionalOnly this publication’s plays.
rowIdstringOptionalOnly 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.
customerstring (uuid)OptionalOnly 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.playedFromstring (date)OptionalFirst day, on the screen’s own clock, inclusive.
playedTostring (date)OptionalLast day, on the screen’s own clock, inclusive.
Returns
A page of plays.
An object with:
playsarray of objectsOptionalShow child attributesHide child attributes
idstringOptionalA stable id for the play.
sourcestringOptionalPossible values
mestraplayedBystringOptionalWhich player showed the play:
standbywhen the screen’s backup player showed any part of it while the main player was being repaired, elsemain. Plays stored before this existed readmain.sourceis the kind of screen, not this.Possible values
mainstandbyscreenIdstring (uuid)OptionalscreenNamestringOptionalEmpty when the screen has been removed.
frameobjectOptionalNullableThe frame of the screen the play was in; null for a play of the whole window.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
siteobjectOptionalNullableThe site the screen was linked to when it played, the same
{key, name}a screen’ssitehas; null when it had none. Plays stored before this was recorded show the screen’s current link.Show child attributesHide child attributes
keystringOptionalThe brand code.
namestringOptional
batchobjectOptionalNullableThe signed batch of plays this play arrived in; read it with
GET /player/plays/batches/{id}. Null for a play stored before batches.Show child attributesHide child attributes
idstring (uuid)Required
publicationIdstring (uuid)OptionalitemIdstring (uuid)OptionalentryIdstring (uuid)OptionalplayedAtLocalstringOptionalThe play’s start on the screen’s own clock,
YYYY-MM-DDTHH:MM:SS.mmm.outOfStepbooleanOptionalTrue 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.
inStepPctintegerOptionalFor a group item’s play: the share of the slot the member was in step, in percent. Absent for a single screen’s play.
stepP95MsintegerOptionalFor 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.
zonestringOptionalThe screen’s time zone.
playedAtstring (date-time)OptionalThe start as a UTC time.
durationMsintegerOptionalsha256stringOptionalcheckobjectOptionalShow child attributesHide child attributes
statestringOptionalPossible values
signedcheckeduncheckedrenderCheckIdstring (uuid)OptionalNullablereceiptobjectOptionalNullableThe signed receipt when
stateissigned, else null.
nextstringOptionalNullableThe 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.
morebooleanOptionalTrue while another page is ready now; false on the last. Ask again later with
nextto follow the feed.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A bad | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connectedunknown_screenunknown_customerunknown_site |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve play totals
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.
Query parameters
groupBystringRequiredWhat to count by.
dayis the screen’s own date.customeris the customer of the booking now, named as it is named now; plays of a booking with no customer arekeyempty,label“No customer”.Possible values
publicationscreensitecustomerdayscreenstring (uuid)OptionalOnly 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.
sitestringOptionalOnly 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.
publicationstring (uuid)OptionalOnly this publication’s plays.
rowIdstringOptionalOnly 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.
customerstring (uuid)OptionalOnly 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.playedFromstring (date)OptionalFirst day, on the screen’s own clock, inclusive.
playedTostring (date)OptionalLast day, on the screen’s own clock, inclusive.
Returns
The totals.
An object with:
groupBystringOptionalPossible values
publicationscreensitecustomerdayrowsarray of objectsOptionalShow child attributesHide child attributes
keystringOptionalThe group: a publication id, a screen id, a site code (empty for no site) or a date.
labelstringOptionalThe publication’s campaign key, the screen’s name, the site code, or the date.
playsintegerOptionaldurationMsintegerOptionalscreensintegerOptionalScreens that played.
signedintegerOptionalPlays 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 thesignedplays the feed and export show.checkedintegerOptionalPlays whose file passed a check with no signed receipt stored.
uncheckedintegerOptionalPlays whose file had no check.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A missing or unknown | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connectedunknown_screenunknown_customerunknown_site |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Download plays as CSV
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.
Query parameters
screenstring (uuid)OptionalOnly 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.
sitestringOptionalOnly 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.
publicationstring (uuid)OptionalOnly this publication’s plays.
rowIdstringOptionalOnly 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.
customerstring (uuid)OptionalOnly 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.playedFromstring (date)OptionalFirst day, on the screen’s own clock, inclusive.
playedTostring (date)OptionalLast day, on the screen’s own clock, inclusive.
Returns
The plays, as CSV.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | A bad date or id ( | |
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | not_connectedunknown_screenunknown_customerunknown_site |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |
Retrieve a signed batch of plays
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. 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).
Path parameters
idstring (uuid)Required
Returns
The batch and its plays.
An object with:
batchobjectRequiredShow child attributesHide child attributes
idstring (uuid)RequiredscreenIdstring (uuid)RequiredreceivedAtstring (date-time)RequiredWhen Mestra received the upload, to the microsecond.
playsintegerRequiredHow many plays the batch holds; the length of
plays.signedbooleanRequiredreceiptobjectRequiredNullableMestra’s signature over the batch:
version,keyId,orgId,screenId,batchId,receivedAt,plays,playsDigest,createdAtandsignature. Null whensignedis false.
playsarray of objectsRequiredShow child attributesHide child attributes
idstringOptionalA stable id for the play.
sourcestringOptionalPossible values
mestraplayedBystringOptionalWhich player showed the play:
standbywhen the screen’s backup player showed any part of it while the main player was being repaired, elsemain. Plays stored before this existed readmain.sourceis the kind of screen, not this.Possible values
mainstandbyscreenIdstring (uuid)OptionalscreenNamestringOptionalEmpty when the screen has been removed.
frameobjectOptionalNullableThe frame of the screen the play was in; null for a play of the whole window.
Show child attributesHide child attributes
idstring (uuid)OptionalnamestringOptional
siteobjectOptionalNullableThe site the screen was linked to when it played, the same
{key, name}a screen’ssitehas; null when it had none. Plays stored before this was recorded show the screen’s current link.Show child attributesHide child attributes
keystringOptionalThe brand code.
namestringOptional
batchobjectOptionalNullableThe signed batch of plays this play arrived in; read it with
GET /player/plays/batches/{id}. Null for a play stored before batches.Show child attributesHide child attributes
idstring (uuid)Required
publicationIdstring (uuid)OptionalitemIdstring (uuid)OptionalentryIdstring (uuid)OptionalplayedAtLocalstringOptionalThe play’s start on the screen’s own clock,
YYYY-MM-DDTHH:MM:SS.mmm.outOfStepbooleanOptionalTrue 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.
inStepPctintegerOptionalFor a group item’s play: the share of the slot the member was in step, in percent. Absent for a single screen’s play.
stepP95MsintegerOptionalFor 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.
zonestringOptionalThe screen’s time zone.
playedAtstring (date-time)OptionalThe start as a UTC time.
durationMsintegerOptionalsha256stringOptionalcheckobjectOptionalShow child attributesHide child attributes
statestringOptionalPossible values
signedcheckeduncheckedrenderCheckIdstring (uuid)OptionalNullablereceiptobjectOptionalNullableThe signed receipt when
stateissigned, else null.
Errors
| Status | Code | Meaning |
|---|---|---|
401 | invalid_token | The key is missing, unknown, revoked or expired (code |
403 | wrong_key |
|
404 | unknown_batchbatch_incompletenot_connected |
|
409 | api_offintegration_off |
|
501 | The player is not available on this server. |