0
# Data Module
1

2
The Data module provides comprehensive analytics and monitoring capabilities including metrics queries, real-time data, video views, incidents, dimensions, filters, and data exports for monitoring video performance and viewer behavior.
3

4
## Imports
5

6
```typescript
7
import Mux from '@mux/mux-node';
8

9
const client = new Mux({
10
  tokenId: 'YOUR_TOKEN_ID',
11
  tokenSecret: 'YOUR_TOKEN_SECRET',
12
});
13

14
// Access data resources
15
const metrics = client.data.metrics;
16
const videoViews = client.data.videoViews;
17
const incidents = client.data.incidents;
18
```
19

20
## Capabilities
21

22
### Metrics
23

24
Query metrics and analytics data with filtering, timeframes, and breakdowns.
25

26
```typescript { .api }
27
interface Metrics {
28
  /**
29
   * List available metrics
30
   */
31
  list(query?: MetricListParams, options?: RequestOptions): Promise<AllMetricValuesResponse>;
32

33
  /**
34
   * Get overall metric values
35
   */
36
  getOverallValues(
37
    metricId: string,
38
    query?: MetricGetOverallValuesParams,
39
    options?: RequestOptions
40
  ): Promise<OverallValuesResponse>;
41

42
  /**
43
   * Get metric timeseries data
44
   */
45
  getTimeseries(
46
    metricId: string,
47
    query?: MetricGetTimeseriesParams,
48
    options?: RequestOptions
49
  ): Promise<MetricTimeseriesDataResponse>;
50

51
  /**
52
   * Get metric breakdown by dimension
53
   */
54
  listBreakdownValues(
55
    metricId: string,
56
    query?: MetricListBreakdownValuesParams,
57
    options?: RequestOptions
58
  ): PagePromise<BreakdownValuesBasePage, BreakdownValue>;
59

60
  /**
61
   * Get metric insights and recommendations
62
   */
63
  getInsights(
64
    metricId: string,
65
    query?: MetricGetInsightsParams,
66
    options?: RequestOptions
67
  ): Promise<InsightsResponse>;
68
}
69

70
interface MetricGetOverallValuesParams {
71
  /** Time range [start, end] */
72
  timeframe?: Array<string>;
73
  /** Filter conditions */
74
  filters?: Array<string>;
75
  /** Measurement type */
76
  measurement?: string;
77
}
78

79
interface MetricGetTimeseriesParams {
80
  /** Time range [start, end] */
81
  timeframe?: Array<string>;
82
  /** Filter conditions */
83
  filters?: Array<string>;
84
  /** Measurement type */
85
  measurement?: string;
86
  /** Sort direction ('asc', 'desc') */
87
  order_direction?: 'asc' | 'desc';
88
}
89

90
interface MetricListBreakdownValuesParams {
91
  /** Dimension to group by */
92
  group_by?: string;
93
  /** Time range [start, end] */
94
  timeframe?: Array<string>;
95
  /** Filter conditions */
96
  filters?: Array<string>;
97
  /** Measurement type */
98
  measurement?: string;
99
  /** Sort field */
100
  order_by?: string;
101
  /** Sort direction ('asc', 'desc') */
102
  order_direction?: 'asc' | 'desc';
103
  /** Items per page */
104
  limit?: number;
105
}
106

107
interface BreakdownValue {
108
  /** Dimension value */
109
  value: string;
110
  /** Total count */
111
  total_count?: number;
112
  /** Field name */
113
  field?: string;
114
  /** View count */
115
  views?: number;
116
  /** Negative impact score */
117
  negative_impact?: number;
118
}
119
```
120

121
**Usage Example:**
122

123
```typescript
124
// Get overall metric values
125
const metrics = await client.data.metrics.getOverallValues('video_startup_time', {
126
  timeframe: ['7:days'],
127
  filters: ['asset_id:ASSET_ID'],
128
});
129

130
// Get metric breakdown by browser
131
const breakdown = await client.data.metrics.listBreakdownValues('video_startup_time', {
132
  group_by: 'browser',
133
  timeframe: ['7:days'],
134
  filters: ['asset_id:ASSET_ID'],
135
  limit: 10,
136
});
137
```
138

139
### Real-Time Analytics
140

141
Query real-time analytics data (last 60 seconds).
142

143
```typescript { .api }
144
interface RealTime {
145
  /**
146
   * List available real-time dimensions
147
   */
148
  listDimensions(options?: RequestOptions): Promise<RealTimeDimensionsResponse>;
149

150
  /**
151
   * List available real-time metrics
152
   */
153
  listMetrics(options?: RequestOptions): Promise<RealTimeMetricsResponse>;
154

155
  /**
156
   * Get real-time metric breakdown
157
   */
158
  retrieveBreakdown(
159
    realtimeMetricId: string,
160
    query?: RealTimeRetrieveBreakdownParams,
161
    options?: RequestOptions
162
  ): Promise<RealTimeBreakdownResponse>;
163

164
  /**
165
   * Get real-time metric timeseries
166
   */
167
  retrieveTimeseries(
168
    realtimeMetricId: string,
169
    query?: RealTimeRetrieveTimeseriesParams,
170
    options?: RequestOptions
171
  ): Promise<RealTimeTimeseriesResponse>;
172

173
  /**
174
   * Get real-time histogram timeseries
175
   */
176
  retrieveHistogramTimeseries(
177
    realtimeHistogramMetricId: string,
178
    query?: RealTimeRetrieveHistogramTimeseriesParams,
179
    options?: RequestOptions
180
  ): Promise<RealTimeHistogramTimeseriesResponse>;
181
}
182

183
interface RealTimeRetrieveBreakdownParams {
184
  /** Dimension to group by */
185
  dimension?: string;
186
  /** Filter conditions */
187
  filters?: Array<string>;
188
  /** Sort field */
189
  order_by?: string;
190
  /** Sort direction ('asc', 'desc') */
191
  order_direction?: 'asc' | 'desc';
192
  /** Unix timestamp */
193
  timestamp?: number;
194
}
195

196
interface RealTimeRetrieveTimeseriesParams {
197
  /** Filter conditions */
198
  filters?: Array<string>;
199
  /** Unix timestamp */
200
  timestamp?: number;
201
}
202
```
203

204
**Usage Example:**
205

206
```typescript
207
// Get current concurrent viewers
208
const breakdown = await client.data.realTime.retrieveBreakdown('current-concurrent-viewers', {
209
  dimension: 'assetId',
210
  filters: ['asset_id:ASSET_ID'],
211
});
212
```
213

214
### Video Views
215

216
Query individual video view session data.
217

218
```typescript { .api }
219
interface VideoViews {
220
  /**
221
   * Retrieve detailed video view data
222
   */
223
  retrieve(viewId: string, options?: RequestOptions): Promise<VideoViewResponse>;
224

225
  /**
226
   * List video views
227
   */
228
  list(query?: VideoViewListParams, options?: RequestOptions): PagePromise<AbridgedVideoViewsBasePage, AbridgedVideoView>;
229
}
230

231
interface VideoViewListParams {
232
  /** Items per page */
233
  limit?: number;
234
  /** Page number */
235
  page?: number;
236
  /** Filter by viewer ID */
237
  viewer_id?: string;
238
  /** Filter by error ID */
239
  error_id?: string;
240
  /** Sort direction ('asc', 'desc') */
241
  order_direction?: 'asc' | 'desc';
242
  /** Filter conditions */
243
  filters?: Array<string>;
244
  /** Time range [start, end] */
245
  timeframe?: Array<string>;
246
}
247

248
interface AbridgedVideoView {
249
  /** View identifier */
250
  id: string;
251
  /** Viewer OS */
252
  viewer_os_family?: string;
253
  /** Device name */
254
  viewer_device_name?: string;
255
  /** Application name */
256
  viewer_application_name?: string;
257
  /** Video title */
258
  video_title?: string;
259
  /** Total views */
260
  total_row_count?: number;
261
  /** View timestamp */
262
  created_at?: string;
263
  /** Start timestamp */
264
  view_start?: string;
265
  /** End timestamp */
266
  view_end?: string;
267
  /** Watch time in milliseconds */
268
  watched_time?: number;
269
  /** Player instance ID */
270
  player_instance_id?: string;
271
}
272
```
273

274
**Usage Example:**
275

276
```typescript
277
// List video views for an asset
278
const views = await client.data.videoViews.list({
279
  filters: ['asset_id:ASSET_ID'],
280
  timeframe: ['7:days'],
281
  limit: 100,
282
});
283

284
for await (const view of views) {
285
  console.log(view.id, view.watched_time);
286
}
287
```
288

289
### Incidents
290

291
Track and manage playback incidents.
292

293
```typescript { .api }
294
interface Incidents {
295
  /**
296
   * Retrieve incident details
297
   */
298
  retrieve(incidentId: string, options?: RequestOptions): Promise<Incident>;
299

300
  /**
301
   * List incidents
302
   */
303
  list(query?: IncidentListParams, options?: RequestOptions): PagePromise<IncidentsBasePage, Incident>;
304

305
  /**
306
   * List related incidents
307
   */
308
  listRelated(
309
    incidentId: string,
310
    query?: IncidentListRelatedParams,
311
    options?: RequestOptions
312
  ): PagePromise<IncidentsBasePage, Incident>;
313
}
314

315
interface IncidentListParams {
316
  /** Items per page */
317
  limit?: number;
318
  /** Page number */
319
  page?: number;
320
  /** Sort order */
321
  order_by?: string;
322
  /** Sort direction ('asc', 'desc') */
323
  order_direction?: 'asc' | 'desc';
324
  /** Filter by status ('open', 'resolved') */
325
  status?: 'open' | 'resolved';
326
  /** Filter by severity ('warning', 'alert') */
327
  severity?: 'warning' | 'alert';
328
}
329

330
interface Incident {
331
  /** Unique identifier */
332
  id: string;
333
  /** Incident status ('open', 'resolved') */
334
  status: 'open' | 'resolved';
335
  /** Severity level ('warning', 'alert') */
336
  severity: 'warning' | 'alert';
337
  /** Start timestamp */
338
  started_at?: string;
339
  /** Resolution timestamp */
340
  resolved_at?: string;
341
  /** Incident description */
342
  description?: string;
343
  /** Number of affected views */
344
  affected_views?: number;
345
  /** Breakdown data */
346
  breakdowns?: Array<object>;
347
  /** Error details */
348
  error_description?: string;
349
  /** Measurement data */
350
  measurement?: object;
351
}
352
```
353

354
### Dimensions
355

356
Query available dimension values for filtering analytics data.
357

358
```typescript { .api }
359
interface Dimensions {
360
  /**
361
   * List available dimensions
362
   */
363
  list(options?: RequestOptions): Promise<DimensionsResponse>;
364

365
  /**
366
   * List values for a specific dimension
367
   */
368
  listValues(
369
    dimensionId: string,
370
    query?: DimensionListValuesParams,
371
    options?: RequestOptions
372
  ): PagePromise<DimensionValuesBasePage, DimensionValue>;
373

374
  /**
375
   * List trace elements for debugging
376
   */
377
  listTraceElements(
378
    dimensionId: string,
379
    query?: DimensionListTraceElementsParams,
380
    options?: RequestOptions
381
  ): PagePromise<DimensionValuesBasePage, DimensionValue>;
382
}
383

384
interface DimensionListValuesParams {
385
  /** Items per page */
386
  limit?: number;
387
  /** Page number */
388
  page?: number;
389
  /** Filter conditions */
390
  filters?: Array<string>;
391
  /** Time range */
392
  timeframe?: Array<string>;
393
}
394

395
interface DimensionsResponse {
396
  /** Available dimensions */
397
  data?: {
398
    /** Basic dimensions */
399
    basic?: Array<string>;
400
    /** Advanced dimensions */
401
    advanced?: Array<string>;
402
  };
403
}
404

405
interface DimensionValue {
406
  /** Dimension value */
407
  value: string;
408
  /** Display-friendly value */
409
  display_value?: string;
410
  /** Total occurrences */
411
  total_count?: number;
412
}
413
```
414

415
### Filters
416

417
Query available filter values.
418

419
```typescript { .api }
420
interface Filters {
421
  /**
422
   * List available filters
423
   */
424
  list(options?: RequestOptions): Promise<FiltersResponse>;
425

426
  /**
427
   * List values for a specific filter
428
   */
429
  listValues(
430
    filterId: string,
431
    query?: FilterListValuesParams,
432
    options?: RequestOptions
433
  ): PagePromise<FilterValuesBasePage, FilterValue>;
434
}
435

436
interface FilterListValuesParams {
437
  /** Items per page */
438
  limit?: number;
439
  /** Page number */
440
  page?: number;
441
  /** Additional filters */
442
  filters?: Array<string>;
443
  /** Time range */
444
  timeframe?: Array<string>;
445
}
446

447
interface FilterValue {
448
  /** Filter value */
449
  value: string;
450
  /** Display-friendly value */
451
  display_value?: string;
452
  /** Total occurrences */
453
  total_count?: number;
454
}
455
```
456

457
### Errors
458

459
Query playback error data.
460

461
```typescript { .api }
462
interface Errors {
463
  /**
464
   * List error occurrences
465
   */
466
  list(query?: ErrorListParams, options?: RequestOptions): Promise<ErrorsResponse>;
467
}
468

469
interface ErrorListParams {
470
  /** Filter conditions */
471
  filters?: Array<string>;
472
  /** Time range */
473
  timeframe?: Array<string>;
474
}
475
```
476

477
### Exports
478

479
Export analytics data.
480

481
```typescript { .api }
482
interface Exports {
483
  /**
484
   * List available video view data exports
485
   */
486
  listVideoViews(options?: RequestOptions): Promise<VideoViewExportsResponse>;
487
}
488
```
489

490
### Monitoring
491

492
Monitoring and alerting metrics.
493

494
```typescript { .api }
495
interface Monitoring {
496
  /**
497
   * List available monitoring dimensions
498
   */
499
  listDimensions(options?: RequestOptions): Promise<MonitoringListDimensionsResponse>;
500

501
  /** Access monitoring metrics */
502
  metrics: MonitoringMetrics;
503
}
504

505
interface MonitoringMetrics {
506
  /**
507
   * List available monitoring metrics
508
   */
509
  list(options?: RequestOptions): Promise<MetricListResponse>;
510

511
  /**
512
   * Get breakdown information for a specific dimension and metric
513
   */
514
  getBreakdown(
515
    monitoringMetricId:
516
      | 'current-concurrent-viewers'
517
      | 'current-rebuffering-percentage'
518
      | 'exits-before-video-start'
519
      | 'playback-failure-percentage'
520
      | 'current-average-bitrate'
521
      | 'video-startup-failure-percentage',
522
    query?: MetricGetBreakdownParams,
523
    options?: RequestOptions
524
  ): Promise<MetricGetBreakdownResponse>;
525

526
  /**
527
   * Get timeseries of breakdown information for a specific dimension and metric
528
   */
529
  getBreakdownTimeseries(
530
    monitoringMetricId:
531
      | 'current-concurrent-viewers'
532
      | 'current-rebuffering-percentage'
533
      | 'exits-before-video-start'
534
      | 'playback-failure-percentage'
535
      | 'current-average-bitrate'
536
      | 'video-startup-failure-percentage',
537
    query?: MetricGetBreakdownTimeseriesParams,
538
    options?: RequestOptions
539
  ): Promise<MetricGetBreakdownTimeseriesResponse>;
540

541
  /**
542
   * Get histogram timeseries information for a specific metric
543
   */
544
  getHistogramTimeseries(
545
    monitoringHistogramMetricId: 'video-startup-time',
546
    query?: MetricGetHistogramTimeseriesParams,
547
    options?: RequestOptions
548
  ): Promise<MetricGetHistogramTimeseriesResponse>;
549

550
  /**
551
   * Get timeseries data for a specific monitoring metric
552
   */
553
  getTimeseries(
554
    monitoringMetricId:
555
      | 'current-concurrent-viewers'
556
      | 'current-rebuffering-percentage'
557
      | 'exits-before-video-start'
558
      | 'playback-failure-percentage'
559
      | 'current-average-bitrate'
560
      | 'video-startup-failure-percentage',
561
    query?: MetricGetTimeseriesParams,
562
    options?: RequestOptions
563
  ): Promise<MetricGetTimeseriesResponse>;
564
}
565
```
566

567
[Analytics and Metrics Documentation](./analytics-metrics.md)
568

569
### Annotations
570

571
Create and manage custom annotations for marking events in analytics data.
572

573
```typescript { .api }
574
interface Annotations {
575
  /**
576
   * Create a new annotation
577
   */
578
  create(body: AnnotationCreateParams, options?: RequestOptions): Promise<Annotation>;
579

580
  /**
581
   * Retrieve annotation details
582
   */
583
  retrieve(annotationId: string, options?: RequestOptions): Promise<Annotation>;
584

585
  /**
586
   * Update annotation
587
   */
588
  update(
589
    annotationId: string,
590
    body: AnnotationUpdateParams,
591
    options?: RequestOptions
592
  ): Promise<Annotation>;
593

594
  /**
595
   * List annotations
596
   */
597
  list(query?: AnnotationListParams, options?: RequestOptions): PagePromise<AnnotationsBasePage, Annotation>;
598

599
  /**
600
   * Delete annotation
601
   */
602
  delete(annotationId: string, options?: RequestOptions): Promise<void>;
603
}
604

605
interface AnnotationCreateParams {
606
  /** Annotation text */
607
  value: string;
608
  /** Event timestamp */
609
  timestamp: string;
610
}
611

612
interface Annotation {
613
  /** Unique identifier */
614
  id: string;
615
  /** Annotation text */
616
  value: string;
617
  /** Event timestamp */
618
  timestamp: string;
619
  /** Creation timestamp */
620
  created_at: string;
621
  /** Last update timestamp */
622
  updated_at?: string;
623
}
624

625
interface AnnotationUpdateParams {
626
  /** Updated annotation text */
627
  value?: string;
628
  /** Updated timestamp */
629
  timestamp?: string;
630
}
631

632
interface AnnotationListParams {
633
  /** Items per page */
634
  limit?: number;
635
  /** Page number */
636
  page?: number;
637
}
638
```
639

640
**Usage Example:**
641

642
```typescript
643
// Create an annotation for a deployment
644
const annotation = await client.data.annotations.create({
645
  value: 'Deployed version 2.0',
646
  timestamp: new Date().toISOString(),
647
});
648
```
649

650
## Common Patterns
651

652
### Filtering
653

654
Filters use a `key:value` format to filter analytics data:
655

656
```typescript
657
// Filter by asset ID
658
filters: ['asset_id:ASSET_ID']
659

660
// Multiple filters (AND logic)
661
filters: ['asset_id:ASSET_ID', 'country:US']
662

663
// Filter by multiple values (OR logic)
664
filters: ['country:US,CA,GB']
665
```
666

667
### Timeframes
668

669
Timeframes specify the time range for queries:
670

671
```typescript
672
// Relative timeframe
673
timeframe: ['7:days']  // Last 7 days
674
timeframe: ['24:hours'] // Last 24 hours
675

676
// Absolute timeframe
677
timeframe: ['2024-01-01T00:00:00Z', '2024-01-31T23:59:59Z']
678
```
679

680
### Pagination
681

682
All list endpoints support pagination:
683

684
```typescript
685
// Manual pagination
686
const page1 = await client.data.videoViews.list({ limit: 100, page: 1 });
687
const page2 = await client.data.videoViews.list({ limit: 100, page: 2 });
688

689
// Auto-pagination with async iteration
690
for await (const view of client.data.videoViews.list({ limit: 100 })) {
691
  console.log(view.id);
692
}
693
```
694