Analytics
Tools for querying the AdHawk analytics engine. All analytics tools share common date-range and device-filter parameters and require startDate and endDate.
Common Parameters
These parameters are available on all analytics tools:
| Parameter | Type | Required | Description |
|---|---|---|---|
startDate |
string | Yes | Start date/time in ISO 8601 format |
endDate |
string | Yes | End date/time in ISO 8601 format |
deviceId |
string or string[] | No | Filter by device ID(s) |
limit |
number | No | Maximum results to return (max: 10000) |
Play & Content Logs
get_play_logs
Retrieve raw content play log entries. Each entry records a single media play event with timestamp, duration, media file ID, and device ID. Useful for detailed auditing.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
fileId |
string or string[] | No | Filter by media file ID(s) |
get_ping_logs
Retrieve device connectivity (ping) logs. Each entry records a device check-in with timestamp, IP address, CPU usage, memory usage, and connection type.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
type |
number or number[] | No | Filter by ping log type(s) |
minCpuUsage |
number | No | Minimum CPU usage percentage |
minMemoryUsage |
number | No | Minimum memory usage percentage |
get_event_logs
Retrieve custom event log entries. Events are application-defined occurrences (e.g. user interactions, sensor triggers) logged by templates or player scripts.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
eventName |
string or string[] | No | Filter by event name(s) |
sessionId |
string | No | Filter by session ID |
Aggregated Metrics
get_event_metrics
Retrieve aggregated metrics for custom events. Returns counts and distributions over time.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
eventName |
string or string[] | No | Filter by event name(s) |
interval |
string | No | Time bucket: minute, hour, day, week, month |
groupByDevice |
boolean | No | Group results by device |
groupByEvent |
boolean | No | Group results by event name |
get_device_metrics
Retrieve device health and performance metrics including uptime, storage, memory, CPU statistics, and connection quality over time.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
interval |
string | No | Time bucket: minute, hour, day, week, month |
get_media_play_stats
Retrieve play statistics per media item — total play count, total duration, average duration, and unique device count.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
fileId |
string or string[] | No | Filter by media file ID(s) |
get_device_play_stats
Retrieve play statistics per device — total play count, total duration, and content utilization.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
fileId |
string or string[] | No | Filter by media file ID(s) |
get_play_stats_by_time
Retrieve play statistics bucketed by time interval. Useful for identifying peak content display times and trends.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
fileId |
string or string[] | No | Filter by media file ID(s) |
interval |
string | No | Time bucket: minute, hour, day, week, month |
groupByDevice |
boolean | No | Group results by device |
groupByFile |
boolean | No | Group results by media file |
Audience Analytics
These tools require audience analytics hardware (e.g. a camera with face detection).
get_impressions
Retrieve audience impression data. Each impression records a viewer detection with estimated dwell time, demographics, and device ID.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
type |
number or number[] | No | Filter by impression type(s) |
gender |
string | No | Filter by detected gender |
minDwellTime |
number | No | Minimum dwell time in milliseconds |
get_audience_metrics
Retrieve aggregated audience measurement data — viewer count, average dwell time, attention time, and demographic estimates.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
interval |
string | No | Time bucket: minute, hour, day, week, month |
groupByDevice |
boolean | No | Group results by device |
includeDwellTime |
boolean | No | Include dwell time distribution |
get_media_impressions
Retrieve impression data broken down by individual media item — view count, display duration, and audience reach per media asset.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
fileId |
string or string[] | No | Filter by media file ID(s) |
minDwellThreshold |
number | No | Minimum dwell time threshold in ms (default: 100) |
Other
get_event_flow
Retrieve event flow data showing sequences of custom events over time. Useful for understanding user interaction patterns and multi-step engagement flows.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
eventName |
string or string[] | No | Filter by event name(s) |
eventDepthLevel |
number | No | Maximum depth of event sequences (default: 6) |
get_heatmap
Retrieve heatmap data for device activity or audience engagement. Returns time-of-day and day-of-week matrices showing activity intensity.
| Extra Parameter | Type | Required | Description |
|---|---|---|---|
interval |
string | No | Time bucket: minute, hour, day, week, month |