Skip to main content
API docs by Redocly

Wallboard API - Statistics (2.0)

API Support: [email protected]

Proof of Play and display statistics for the Wallboard digital signage platform.

Overview

This API provides detailed analytics on content playback, including:

  • Play duration and impressions
  • Viewer counts and attention metrics
  • Click tracking
  • Audience measurement data

Key Concepts

Concept Description
Proof of Play Verifiable record of content display for compliance/billing
Resolution Time granularity: HOURLY, DAILY, WEEKLY, MONTHLY, TOTAL
GroupBy How to aggregate data (by device, content, campaign, etc.)
Impressions Number of times content was displayed
Duration Total playback time in milliseconds
Viewer Count Estimated audience size (requires audience measurement)
Viewer Attention Time viewers actually watched the content

Time Parameters

All time parameters use Unix timestamps in milliseconds.

Parameter Description
from Start time (required)
to End time (optional, defaults to now)
timeZone Timezone for grouping (default: UTC)

Resolution Limits

Different resolutions have different maximum date ranges:

Resolution Max Range (no groupBy) Max Range (with groupBy)
HOURLY 31 days 8 days
DAILY 31 days 31 days
WEEKLY Unlimited Unlimited
MONTHLY Unlimited Unlimited
TOTAL Unlimited Unlimited

Notes:

  • For "all" endpoints (e.g., /device/all), HOURLY and DAILY resolutions are not allowed
  • Using groupBy with HOURLY resolution limits the date range to 8 days maximum
  • Exceeding these limits returns a 400 Bad Request error

Viewer Metrics (Audience Measurement)

These metrics require audience measurement hardware/software to be configured:

Metric Description
viewerCount Total estimated viewers during playback
viewerAttention Total attention time in milliseconds
viewerAverageAttention Average attention per viewer
viewerAttentionRatio Ratio of actual to potential attention (0-1)

Overlap Prevention Fields: To prevent double-counting viewers when grouping by different dimensions, additional overlap fields are provided:

Field Description
viewerCountOverlapAsset Viewer overlap within same asset
viewerCountOverlapContent Viewer overlap within same content
viewerCountOverlapCampaign Viewer overlap within same campaign
viewerCountOverlapDevice Viewer overlap on same device

These fields help calculate unique viewers across different aggregation levels.

dashboard

Dashboard summary endpoints

Get top played contents

Get the most played content items for dashboard display.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>

Start time (Unix timestamp in milliseconds)

to
integer <int64>

End time (Unix timestamp in milliseconds, defaults to now)

timeZone
string
Default: "UTC"

Timezone for grouping

limit
integer
Default: 5

Number of results

search
string

WBQL search filter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get top played campaigns

Get the most played campaigns/channels for dashboard display.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>

Start time (Unix timestamp in milliseconds)

to
integer <int64>

End time (Unix timestamp in milliseconds, defaults to now)

timeZone
string
Default: "UTC"

Timezone for grouping

limit
integer
Default: 5

Number of results

search
string

WBQL search filter

Responses

Response samples

Content type
application/json
[
  • {
    }
]

device statistics

Display statistics by device

Get statistics for all devices

Retrieve play statistics aggregated across all devices.

Note: HOURLY and DAILY resolutions are not allowed for all-device queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>

Start time (Unix timestamp in milliseconds)

to
integer <int64>

End time (Unix timestamp in milliseconds)

resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for grouping

timeZone
string
Default: "UTC"
sort
string

Sort field and direction (e.g., "duration,desc")

offset
integer
limit
integer
search
string

WBQL search filter

Responses

Request samples 

# Get weekly device statistics for the last month
curl -X GET \
  'https://{server}/api/v2/proof-of-display/device/all?from=1704067200000&to=1706745600000&resolution=WEEKLY&timeZone=Europe/Budapest' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

Export all device statistics as CSV

Export play statistics for all devices as CSV file.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Get statistics for a specific device

Retrieve play statistics for a single device.

GroupBy options:

  • CONTENT - Group by content
  • CONTENT_PAGE - Group by content page/slide
  • CUSTOM_ASSET - Group by custom asset
  • CAMPAIGN - Group by campaign/channel
  • ADVERTISER - Group by advertiser
  • MEDIA_FILE - Group by media file
  • WIDGET - Group by widget

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
deviceId
required
string

Device UUID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (DeviceGroupBy)
Enum: "CONTENT" "CONTENT_PAGE" "CUSTOM_ASSET" "CAMPAIGN" "ADVERTISER" "MEDIA_FILE" "WIDGET"

How to aggregate the data

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get hourly statistics for a device, grouped by content
curl -X GET \
  'https://{server}/api/v2/proof-of-display/device/abc-123-def?from=1704067200000&resolution=HOURLY&groupBy=CONTENT' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

Export device statistics as CSV

Export play statistics for a specific device as CSV file.

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
deviceId
required
string
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (DeviceGroupBy)
Enum: "CONTENT" "CONTENT_PAGE" "CUSTOM_ASSET" "CAMPAIGN" "ADVERTISER" "MEDIA_FILE" "WIDGET"

Grouping options for device statistics

timeZone
string
Default: "UTC"

Responses

device group statistics

Display statistics by device group

Get statistics for all device groups

Retrieve play statistics aggregated across all device groups.

Note: HOURLY and DAILY resolutions are not allowed for all-device-group queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get statistics for specific device group

Retrieve play statistics for a single device group.

GroupBy options:

  • CONTENT - Group by content
  • CONTENT_PAGE - Group by content page/slide
  • CAMPAIGN - Group by campaign/channel
  • ADVERTISER - Group by advertiser
  • MEDIA_FILE - Group by media file
  • WIDGET - Group by widget

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
deviceGroupId
required
string

Device group UUID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (DeviceGroupGroupBy)
Enum: "CONTENT" "CONTENT_PAGE" "CAMPAIGN" "ADVERTISER" "MEDIA_FILE" "WIDGET"

Grouping options for device group statistics

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get weekly statistics for a device group, grouped by content
curl -X GET \
  'https://{server}/api/v2/proof-of-display/deviceGroup/dg-uuid-123?from=1704067200000&resolution=WEEKLY&groupBy=CONTENT' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

content statistics

Display statistics by content

Get statistics for all content

Retrieve play statistics aggregated across all content.

GroupBy options:

  • CONTENT_PAGE - Group by content page/slide
  • DEVICE - Group by device
  • WIDGET - Group by widget

Note: HOURLY and DAILY resolutions are not allowed for all-content queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (ContentGroupBy)
Enum: "CONTENT_PAGE" "DEVICE" "WIDGET"

Grouping options for all-content statistics

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get statistics for specific content

Retrieve play statistics for a single content item.

GroupBy options:

  • CONTENT_PAGE - Group by page/slide
  • DEVICE - Group by device
  • DEVICE_GROUP - Group by device group
  • CUSTOM_ASSET - Group by custom asset
  • MEDIA_FILE - Group by media file
  • WIDGET - Group by widget

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
contentId
required
string

Content UUID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (ContentSingleGroupBy)
Enum: "CONTENT_PAGE" "DEVICE" "DEVICE_GROUP" "CUSTOM_ASSET" "MEDIA_FILE" "WIDGET"

Grouping options for single-content statistics

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get weekly statistics for content, grouped by device
curl -X GET \
  'https://{server}/api/v2/proof-of-display/content/content-uuid-123?from=1704067200000&resolution=WEEKLY&groupBy=DEVICE' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

campaign statistics

Display statistics by campaign/channel

Get statistics for all campaigns

Retrieve play statistics aggregated across all campaigns/channels.

Note: HOURLY and DAILY resolutions are not allowed for all-campaign queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get statistics for specific campaign

Retrieve play statistics for a single campaign/channel.

GroupBy options:

  • CONTENT - Group by content
  • CONTENT_PAGE - Group by content page/slide
  • MEDIA_FILE - Group by media file
  • MESSAGE - Group by sub-channel/message
  • DEVICE - Group by device
  • DEVICE_GROUP - Group by device group

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
campaignId
required
integer <int64>

Campaign/channel ID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (CampaignGroupBy)
Enum: "CONTENT" "CONTENT_PAGE" "MEDIA_FILE" "MESSAGE" "DEVICE" "DEVICE_GROUP"

Grouping options for campaign statistics

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get monthly statistics for a campaign, grouped by content
curl -X GET \
  'https://{server}/api/v2/proof-of-display/campaign/123?from=1704067200000&resolution=MONTHLY&groupBy=CONTENT' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

message statistics

Display statistics by sub-channel/message

Get statistics for all sub-channels

Retrieve play statistics aggregated across all sub-channels/messages.

Note: HOURLY and DAILY resolutions are not allowed for all-message queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get statistics for specific sub-channel

Retrieve play statistics for a single sub-channel/message.

GroupBy options:

  • CONTENT - Group by content
  • CONTENT_PAGE - Group by content page/slide
  • DEVICE - Group by device
  • DEVICE_GROUP - Group by device group

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
messageId
required
integer <int64>

Sub-channel/message ID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (MessageGroupBy)
Enum: "CONTENT" "CONTENT_PAGE" "DEVICE" "DEVICE_GROUP"

Grouping options for message/sub-channel statistics

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get weekly statistics for a sub-channel, grouped by device
curl -X GET \
  'https://{server}/api/v2/proof-of-display/message/456?from=1704067200000&resolution=WEEKLY&groupBy=DEVICE' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

advertiser statistics

Display statistics by advertiser

Get statistics for all advertisers

Retrieve play statistics aggregated across all advertisers.

Note: HOURLY and DAILY resolutions are not allowed for all-advertiser queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get statistics for specific advertiser

Retrieve play statistics for a single advertiser.

GroupBy options:

  • CONTENT - Group by content
  • CONTENT_PAGE - Group by content page/slide
  • CAMPAIGN - Group by campaign/channel
  • MESSAGE - Group by sub-channel/message
  • DEVICE - Group by device
  • DEVICE_GROUP - Group by device group

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
advertiserId
required
string

Advertiser UUID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (AdvertiserGroupBy)
Enum: "CONTENT" "CONTENT_PAGE" "CAMPAIGN" "MESSAGE" "DEVICE" "DEVICE_GROUP"

Grouping options for advertiser statistics

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get monthly statistics for an advertiser, grouped by campaign
curl -X GET \
  'https://{server}/api/v2/proof-of-display/advertiser/adv-uuid-123?from=1704067200000&resolution=MONTHLY&groupBy=CAMPAIGN' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]

widget statistics

Display statistics by widget

Get statistics for all widgets

Retrieve play statistics aggregated across all widgets.

Note: HOURLY and DAILY resolutions are not allowed for all-widget queries.

Minimum role: VIEWER

Authorizations:
bearer
query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

timeZone
string
Default: "UTC"
sort
string
offset
integer
limit
integer
search
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get statistics for specific widget

Retrieve play statistics for a single widget.

GroupBy options:

  • DEVICE - Group by device
  • DEVICE_GROUP - Group by device group
  • CONTENT - Group by content

Minimum role: VIEWER

Authorizations:
bearer
path Parameters
widgetId
required
string

Widget UUID

query Parameters
from
required
integer <int64>
to
integer <int64>
resolution
required
string (Resolution)
Enum: "HOURLY" "DAILY" "WEEKLY" "MONTHLY" "TOTAL"

Time resolution for data aggregation

groupBy
string (WidgetGroupBy)
Enum: "DEVICE" "DEVICE_GROUP" "CONTENT"

Grouping options for widget statistics

timeZone
string
Default: "UTC"

Responses

Request samples 

# Get daily statistics for a widget, grouped by device
curl -X GET \
  'https://{server}/api/v2/proof-of-display/widget/widget-uuid-123?from=1704067200000&resolution=DAILY&groupBy=DEVICE' \
  -H 'Authorization: Bearer <token>'

Response samples

Content type
application/json
[
  • {
    }
]