0
# Analytics and Metrics
1

2
Comprehensive analytics and monitoring data for video performance, viewer behavior, real-time metrics, and system monitoring across the Mux platform.
3

4
## Capabilities
5

6
### Metrics Analysis
7

8
Retrieve and analyze various metrics including views, engagement, quality, and performance data.
9

10
```typescript { .api }
11
/**
12
 * List all available metrics
13
 * @param query - Metric listing parameters
14
 * @returns Promise resolving to all metric values
15
 */
16
list(query?: MetricListParams): Promise<AllMetricValuesResponse>;
17

18
interface MetricListParams {
19
  /** Timeframe for metric data */
20
  timeframe?: Array<string>;
21
  /** Filters to apply to metrics */
22
  filters?: Array<string>;
23
  /** Dimension to break down results by */
24
  dimension?: string;
25
  /** Measurement type */
26
  measurement?: string;
27
}
28

29
interface AllMetricValuesResponse {
30
  /** Array of metric data points */
31
  data: Array<MetricValue>;
32
  /** Total number of data points */
33
  total_row_count?: number;
34
  /** Applied timeframe */
35
  timeframe?: Array<number>;
36
}
37

38
/**
39
 * Get insights for a specific metric
40
 * @param metricId - The metric identifier
41
 * @param query - Insights query parameters
42
 * @returns Promise resolving to metric insights
43
 */
44
getInsights(metricId: string, query?: MetricGetInsightsParams): Promise<InsightsResponse>;
45

46
interface MetricGetInsightsParams {
47
  /** Timeframe for insights */
48
  timeframe?: Array<string>;
49
  /** Filters to apply */
50
  filters?: Array<string>;
51
  /** Measurement type */
52
  measurement?: '95th' | 'median' | 'avg' | 'count' | 'sum';
53
  /** Limit the results to rows that match inequality conditions */
54
  metric_filters?: Array<string>;
55
  /** Order direction */
56
  order_direction?: 'asc' | 'desc';
57
}
58

59
/**
60
 * Returns the overall value for a specific metric, as well as the total view count, watch time, and the Mux Global metric value
61
 * @param metricId - The metric identifier
62
 * @param query - Overall values query parameters
63
 * @returns Promise resolving to overall metric values
64
 */
65
getOverallValues(metricId: string, query?: MetricGetOverallValuesParams): Promise<OverallValuesResponse>;
66

67
interface MetricGetOverallValuesParams {
68
  /** Timeframe for overall values */
69
  timeframe?: Array<string>;
70
  /** Filters to apply */
71
  filters?: Array<string>;
72
  /** Measurement type */
73
  measurement?: '95th' | 'median' | 'avg' | 'count' | 'sum';
74
  /** Limit the results to rows that match inequality conditions */
75
  metric_filters?: Array<string>;
76
}
77

78
interface OverallValuesResponse {
79
  /** Overall values data */
80
  data: OverallValuesData;
81
  /** Metadata */
82
  meta: MetricMeta;
83
  /** Applied timeframe */
84
  timeframe: Array<number>;
85
  /** Total row count */
86
  total_row_count: number | null;
87
}
88

89
interface OverallValuesData {
90
  /** Global value for the metric */
91
  global_value: number | null;
92
  /** Total playing time */
93
  total_playing_time: number | null;
94
  /** Total views */
95
  total_views: number;
96
  /** Total watch time */
97
  total_watch_time: number | null;
98
  /** Calculated metric value */
99
  value: number;
100
}
101

102
/**
103
 * Returns timeseries data for a specific metric
104
 * @param metricId - The metric identifier
105
 * @param query - Timeseries query parameters
106
 * @returns Promise resolving to metric timeseries data
107
 */
108
getTimeseries(metricId: string, query?: MetricGetTimeseriesParams): Promise<MetricTimeseriesDataResponse>;
109

110
interface MetricGetTimeseriesParams {
111
  /** Timeframe for timeseries */
112
  timeframe?: Array<string>;
113
  /** Filters to apply */
114
  filters?: Array<string>;
115
  /** Time granularity to group results by */
116
  group_by?: 'minute' | 'ten_minutes' | 'hour' | 'day';
117
  /** Measurement type */
118
  measurement?: '95th' | 'median' | 'avg' | 'count' | 'sum';
119
  /** Limit the results to rows that match inequality conditions */
120
  metric_filters?: Array<string>;
121
  /** Order direction */
122
  order_direction?: 'asc' | 'desc';
123
}
124

125
interface MetricTimeseriesDataResponse {
126
  /** Timeseries data points - each array contains [timestamp, metric_value, view_count] */
127
  data: Array<Array<string | number | null>>;
128
  /** Metadata */
129
  meta: MetricMeta;
130
  /** Applied timeframe */
131
  timeframe: Array<number>;
132
  /** Total row count */
133
  total_row_count: number;
134
}
135

136
interface MetricMeta {
137
  /** Aggregation method */
138
  aggregation?: string;
139
  /** Time granularity */
140
  granularity?: string;
141
}
142
```
143

144
**Usage Examples:**
145

146
```typescript
147
// Get all video views for the last 7 days
148
const metrics = await mux.data.metrics.list({
149
  timeframe: ['7:days'],
150
  filters: ['operating_system:Windows'],
151
});
152

153
// Get engagement insights for a specific asset
154
const insights = await mux.data.metrics.getInsights('video_startup_time', {
155
  timeframe: ['24:hours'],
156
  filters: ['asset_id:your-asset-id'],
157
  measurement: 'median',
158
});
159

160
// Get breakdown values for video quality
161
const breakdown = await mux.data.metrics.listBreakdownValues('video_quality_score', {
162
  timeframe: ['30:days'],
163
  dimension: 'country',
164
  order_direction: 'desc',
165
});
166
```
167

168
### Real-Time Data
169

170
Access real-time streaming data and live metrics for monitoring current activity.
171

172
```typescript { .api }
173
/**
174
 * List available real-time dimensions
175
 * @returns Promise resolving to real-time dimensions
176
 */
177
listDimensions(): Promise<RealTimeDimensionsResponse>;
178

179
/**
180
 * List available real-time metrics
181
 * @returns Promise resolving to real-time metrics
182
 */
183
listMetrics(): Promise<RealTimeMetricsResponse>;
184

185
/**
186
 * Retrieve real-time breakdown data
187
 * @param realTimeMetricId - The real-time metric identifier
188
 * @param query - Breakdown query parameters
189
 * @returns Promise resolving to real-time breakdown data
190
 */
191
retrieveBreakdown(
192
  realTimeMetricId: string,
193
  query?: RealTimeRetrieveBreakdownParams
194
): Promise<RealTimeBreakdownResponse>;
195

196
interface RealTimeRetrieveBreakdownParams {
197
  /** Dimension to break down by */
198
  dimension?: string;
199
  /** Filters to apply */
200
  filters?: Array<string>;
201
  /** Timestamp for data point */
202
  timestamp?: number;
203
  /** Order direction */
204
  order_direction?: 'asc' | 'desc';
205
  /** Order by field */
206
  order_by?: string;
207
}
208

209
/**
210
 * Retrieve real-time timeseries data
211
 * @param realTimeMetricId - The real-time metric identifier
212
 * @param query - Timeseries query parameters
213
 * @returns Promise resolving to real-time timeseries data
214
 */
215
retrieveTimeseries(
216
  realTimeMetricId: string,
217
  query?: RealTimeRetrieveTimeseriesParams
218
): Promise<RealTimeTimeseriesResponse>;
219
```
220

221
### Video Views Analysis
222

223
Detailed analysis of individual video view sessions and viewer behavior.
224

225
```typescript { .api }
226
/**
227
 * List video views with filtering and pagination
228
 * @param query - Video view listing parameters
229
 * @returns Paginated list of video views
230
 */
231
list(query?: VideoViewListParams): PagePromise<AbridgedVideoViewsBasePage, AbridgedVideoView>;
232

233
interface VideoViewListParams extends BasePageParams {
234
  /** Filter by viewer ID */
235
  viewer_id?: string;
236
  /** Filter by error ID */
237
  error_id?: string;
238
  /** Filter by order direction */
239
  order_direction?: 'asc' | 'desc';
240
  /** Filter by asset ID */
241
  filters?: Array<string>;
242
  /** Metric filters */
243
  metric_filters?: Array<string>;
244
  /** Timeframe for views */
245
  timeframe?: Array<string>;
246
}
247

248
/**
249
 * Retrieve detailed video view information
250
 * @param videoViewId - The video view identifier
251
 * @returns Promise resolving to detailed video view data
252
 */
253
retrieve(videoViewId: string): Promise<VideoViewResponse>;
254

255
interface AbridgedVideoView {
256
  /** Video view identifier */
257
  id?: string;
258
  /** Viewer identifier */
259
  viewer_id?: string;
260
  /** Total view time in seconds */
261
  total_row_count?: number;
262
  /** Player error ID if applicable */
263
  player_error_id?: string;
264
  /** Asset ID being viewed */
265
  asset_id?: string;
266
}
267

268
interface VideoViewResponse {
269
  /** Detailed video view data */
270
  data?: VideoView;
271
}
272

273
interface VideoView {
274
  /** View session identifier */
275
  id?: string;
276
  /** Viewer identifier */
277
  viewer_id?: string;
278
  /** View session creation timestamp */
279
  created_at?: string;
280
  /** Total watch time in milliseconds */
281
  total_row_count?: number;
282
  /** Player software information */
283
  player_software?: string;
284
  /** Player software version */
285
  player_software_version?: string;
286
  /** Operating system */
287
  operating_system?: string;
288
  /** Browser name */
289
  browser?: string;
290
  /** Geographic country */
291
  country?: string;
292
  /** Asset being viewed */
293
  asset_id?: string;
294
  /** Playback ID used */
295
  playback_id?: string;
296
}
297
```
298

299
### Custom Annotations
300

301
Create and manage custom annotations for marking important events and metrics.
302

303
```typescript { .api }
304
/**
305
 * Create a custom annotation
306
 * @param body - Annotation creation parameters
307
 * @returns Promise resolving to the created annotation
308
 */
309
create(body: AnnotationCreateParams): Promise<Annotation>;
310

311
interface AnnotationCreateParams {
312
  /** Datetime when the annotation applies (Unix timestamp) */
313
  date: number;
314
  /** The annotation note content */
315
  note: string;
316
  /** Customer-defined sub-property identifier */
317
  sub_property_id?: string;
318
}
319

320
interface Annotation {
321
  /** Unique identifier for the annotation */
322
  id: string;
323
  /** Datetime when the annotation applies */
324
  date: string;
325
  /** The annotation note content */
326
  note: string;
327
  /** Customer-defined sub-property identifier */
328
  sub_property_id?: string | null;
329
}
330

331
/**
332
 * Returns the details of a specific annotation
333
 * @param annotationId - The annotation ID
334
 * @returns Promise resolving to annotation details
335
 */
336
retrieve(annotationId: string): Promise<Annotation>;
337

338
/**
339
 * Returns a list of annotations
340
 * @param query - Optional query parameters
341
 * @returns Page promise for iterating annotations
342
 */
343
list(query?: AnnotationListParams): PagePromise<AnnotationsBasePage, Annotation>;
344

345
interface AnnotationListParams {
346
  /** Sort order */
347
  order_direction?: 'asc' | 'desc';
348
  /** Timeframe window to limit results */
349
  timeframe?: Array<string>;
350
  /** Page number */
351
  page?: number;
352
  /** Number of items per page */
353
  limit?: number;
354
}
355

356
/**
357
 * Update an existing annotation
358
 * @param annotationId - The annotation identifier
359
 * @param body - Annotation update parameters
360
 * @returns Promise resolving to the updated annotation
361
 */
362
update(annotationId: string, body: AnnotationUpdateParams): Promise<Annotation>;
363

364
/**
365
 * Delete an annotation
366
 * @param annotationId - The annotation identifier
367
 * @returns Promise that resolves when deletion is complete
368
 */
369
delete(annotationId: string): Promise<void>;
370
```
371

372
### Dimensions and Filters
373

374
Explore available dimensions and filter values for data analysis.
375

376
```typescript { .api }
377
/**
378
 * List all available dimensions
379
 * @returns Promise resolving to available dimensions
380
 */
381
list(): Promise<DimensionsResponse>;
382

383
/**
384
 * List values for a specific dimension
385
 * @param dimensionId - The dimension identifier
386
 * @param query - Dimension value listing parameters
387
 * @returns Paginated list of dimension values
388
 */
389
listValues(
390
  dimensionId: string,
391
  query?: DimensionListValuesParams
392
): PagePromise<DimensionValuesBasePage, DimensionValue>;
393

394
interface DimensionListValuesParams extends BasePageParams {
395
  /** Filters to apply */
396
  filters?: Array<string>;
397
  /** Timeframe for values */
398
  timeframe?: Array<string>;
399
}
400

401
interface DimensionValue {
402
  /** Dimension value */
403
  value?: string;
404
  /** Total count for this value */
405
  total_count?: number;
406
}
407

408
/**
409
 * List available filter types
410
 * @returns Promise resolving to available filters
411
 */
412
listFilters(): Promise<FiltersResponse>;
413

414
/**
415
 * List values for a specific filter
416
 * @param filterId - The filter identifier
417
 * @param query - Filter value listing parameters
418
 * @returns Paginated list of filter values
419
 */
420
listFilterValues(
421
  filterId: string,
422
  query?: FilterListValuesParams
423
): PagePromise<FilterValuesBasePage, FilterValue>;
424
```
425

426
### Error Tracking
427

428
Monitor and analyze playback errors and issues.
429

430
```typescript { .api }
431
/**
432
 * List playback errors with filtering
433
 * @param query - Error listing parameters
434
 * @returns Promise resolving to error data
435
 */
436
list(query?: ErrorListParams): Promise<ErrorsResponse>;
437

438
interface ErrorListParams {
439
  /** Filters to apply to errors */
440
  filters?: Array<string>;
441
  /** Timeframe for errors */
442
  timeframe?: Array<string>;
443
}
444

445
interface ErrorsResponse {
446
  /** Array of error data */
447
  data: Array<ErrorData>;
448
  /** Applied timeframe */
449
  timeframe: Array<number>;
450
  /** Total error count */
451
  total_row_count: number | null;
452
}
453

454
interface ErrorData {
455
  /** A unique identifier for this error */
456
  id: number;
457
  /** The error code */
458
  code: number | null;
459
  /** The total number of views that experienced this error */
460
  count: number;
461
  /** Description of the error */
462
  description: string | null;
463
  /** The last time this error was seen (ISO 8601 timestamp) */
464
  last_seen: string;
465
  /** The error message */
466
  message: string | null;
467
  /** Notes that are attached to this error */
468
  notes: string | null;
469
  /** The percentage of views that experienced this error */
470
  percentage: number;
471
  /** The string version of the error code */
472
  player_error_code: string | null;
473
}
474
```
475

476
### Incident Monitoring
477

478
Track service incidents and related system issues.
479

480
```typescript { .api }
481
/**
482
 * List service incidents
483
 * @param query - Incident listing parameters
484
 * @returns Paginated list of incidents
485
 */
486
list(query?: IncidentListParams): PagePromise<IncidentsBasePage, Incident>;
487

488
interface IncidentListParams extends BasePageParams {
489
  /** Value to order the results by */
490
  order_by?: 'negative_impact' | 'value' | 'views' | 'field';
491
  /** Sort order */
492
  order_direction?: 'asc' | 'desc';
493
  /** Severity to filter incidents by */
494
  severity?: 'warning' | 'alert';
495
  /** Status to filter incidents by */
496
  status?: 'open' | 'closed' | 'expired';
497
}
498

499
/**
500
 * Retrieve incident details
501
 * @param incidentId - The incident identifier
502
 * @returns Promise resolving to incident details
503
 */
504
retrieve(incidentId: string): Promise<Incident>;
505

506
/**
507
 * List related incidents
508
 * @param incidentId - The incident identifier
509
 * @param query - Related incident listing parameters
510
 * @returns Paginated list of related incidents
511
 */
512
listRelated(
513
  incidentId: string,
514
  query?: IncidentListRelatedParams
515
): PagePromise<IncidentsBasePage, Incident>;
516

517
interface Incident {
518
  /** Incident identifier */
519
  id: string;
520
  /** Number of affected views */
521
  affected_views: number;
522
  /** Affected views per hour */
523
  affected_views_per_hour: number;
524
  /** Affected views per hour when opened */
525
  affected_views_per_hour_on_open: number;
526
  /** Breakdown details */
527
  breakdowns: Array<IncidentBreakdown>;
528
  /** Incident description */
529
  description: string;
530
  /** Error description */
531
  error_description: string;
532
  /** Impact description */
533
  impact: string;
534
  /** Incident key */
535
  incident_key: string;
536
  /** Measured value */
537
  measured_value: number | null;
538
  /** Measured value on close */
539
  measured_value_on_close: number | null;
540
  /** Measurement type */
541
  measurement: string;
542
  /** Notification rules */
543
  notification_rules: Array<IncidentNotificationRule>;
544
  /** Notifications sent */
545
  notifications: Array<IncidentNotification>;
546
  /** Resolution timestamp */
547
  resolved_at: string | null;
548
  /** Sample size */
549
  sample_size: number;
550
  /** Sample size unit */
551
  sample_size_unit: string;
552
  /** Severity level */
553
  severity: string;
554
  /** Start timestamp */
555
  started_at: string;
556
  /** Current status */
557
  status: string;
558
  /** Threshold value */
559
  threshold: number;
560
}
561

562
interface IncidentBreakdown {
563
  /** Breakdown identifier */
564
  id: string;
565
  /** Breakdown name */
566
  name: string;
567
  /** Breakdown value */
568
  value: string;
569
}
570

571
interface IncidentNotificationRule {
572
  /** Rule identifier */
573
  id: string;
574
  /** Action type */
575
  action: string;
576
  /** Property identifier */
577
  property_id: string;
578
  /** Rule conditions */
579
  rules: Array<{
580
    id: string;
581
    name: string;
582
    value: string;
583
  }>;
584
  /** Rule status */
585
  status: string;
586
}
587

588
interface IncidentNotification {
589
  /** Notification identifier */
590
  id: number;
591
  /** Attempt timestamp */
592
  attempted_at: string;
593
  /** Queued timestamp */
594
  queued_at: string;
595
}
596
```
597

598
### Data Exports
599

600
Manage and retrieve data exports for external analysis.
601

602
```typescript { .api }
603
/**
604
 * List available video view exports
605
 * @returns Promise resolving to available exports
606
 */
607
listVideoViews(): Promise<VideoViewExportsResponse>;
608

609
interface VideoViewExportsResponse {
610
  /** Array of available exports */
611
  data: Array<VideoViewExport>;
612
  /** Applied timeframe */
613
  timeframe: Array<number>;
614
  /** Total row count */
615
  total_row_count: number | null;
616
}
617

618
interface VideoViewExport {
619
  /** Export date */
620
  export_date: string;
621
  /** Export files */
622
  files: Array<VideoViewExportFile>;
623
}
624

625
interface VideoViewExportFile {
626
  /** File path/URL */
627
  path: string;
628
  /** File type */
629
  type: string;
630
  /** File version */
631
  version: number;
632
}
633
```
634

635
## Monitoring
636

637
```typescript { .api }
638
/**
639
 * List monitoring dimensions
640
 * @returns Promise resolving to monitoring dimensions
641
 */
642
listDimensions(): Promise<MonitoringListDimensionsResponse>;
643

644
interface MonitoringListDimensionsResponse {
645
  /** Available monitoring dimensions */
646
  data?: Array<MonitoringDimension>;
647
}
648

649
interface MonitoringDimension {
650
  /** Dimension identifier */
651
  id?: string;
652
  /** Dimension display name */
653
  name?: string;
654
  /** Dimension description */
655
  description?: string;
656
}
657
```
658

659
### Monitoring Metrics
660

661
Real-time monitoring metrics for tracking current playback performance, concurrent viewers, and quality indicators.
662

663
```typescript { .api }
664
/**
665
 * List available monitoring metrics
666
 * @returns Promise resolving to list of available monitoring metrics
667
 */
668
list(): Promise<MetricListResponse>;
669

670
interface MetricListResponse {
671
  /** Available monitoring metrics */
672
  data: Array<{
673
    /** Display name for the metric */
674
    display_name: string;
675
    /** Metric identifier */
676
    name: string;
677
  }>;
678
  /** Applied timeframe */
679
  timeframe: Array<number>;
680
  /** Total row count */
681
  total_row_count: number | null;
682
}
683

684
/**
685
 * Get breakdown information for a specific dimension and metric
686
 * @param monitoringMetricId - Monitoring metric identifier
687
 * @param query - Breakdown query parameters
688
 * @returns Promise resolving to breakdown data with concurrent viewers and negative impact scores
689
 */
690
getBreakdown(
691
  monitoringMetricId: MonitoringMetricId,
692
  query?: MetricGetBreakdownParams
693
): Promise<MetricGetBreakdownResponse>;
694

695
type MonitoringMetricId =
696
  | 'current-concurrent-viewers'
697
  | 'current-rebuffering-percentage'
698
  | 'exits-before-video-start'
699
  | 'playback-failure-percentage'
700
  | 'current-average-bitrate'
701
  | 'video-startup-failure-percentage';
702

703
interface MetricGetBreakdownParams {
704
  /** Dimension to break down by */
705
  dimension?:
706
    | 'asn'
707
    | 'cdn'
708
    | 'country'
709
    | 'operating_system'
710
    | 'player_name'
711
    | 'region'
712
    | 'stream_type'
713
    | 'sub_property_id'
714
    | 'video_series'
715
    | 'video_title'
716
    | 'view_has_ad';
717
  /** Filters to apply (e.g., 'operating_system:windows', '!country:US') */
718
  filters?: Array<string>;
719
  /** Field to order results by */
720
  order_by?: 'negative_impact' | 'value' | 'views' | 'field';
721
  /** Sort order */
722
  order_direction?: 'asc' | 'desc';
723
  /** Unix timestamp to limit results (defaults to current time) */
724
  timestamp?: number;
725
}
726

727
interface MetricGetBreakdownResponse {
728
  /** Breakdown data points */
729
  data: Array<{
730
    /** Number of concurrent viewers */
731
    concurrent_viewers: number;
732
    /** Calculated metric value */
733
    metric_value: number | null;
734
    /** Negative impact score */
735
    negative_impact: number;
736
    /** Number of viewers in startup phase */
737
    starting_up_viewers: number;
738
    /** Dimension value */
739
    value: string | null;
740
    /** Human-readable display value */
741
    display_value?: string;
742
  }>;
743
  /** Applied timeframe */
744
  timeframe: Array<number>;
745
  /** Total row count */
746
  total_row_count: number | null;
747
}
748

749
/**
750
 * Get timeseries of breakdown information for a specific dimension and metric
751
 * @param monitoringMetricId - Monitoring metric identifier
752
 * @param query - Breakdown timeseries query parameters
753
 * @returns Promise resolving to timeseries breakdown data (5-second intervals)
754
 */
755
getBreakdownTimeseries(
756
  monitoringMetricId: MonitoringMetricId,
757
  query?: MetricGetBreakdownTimeseriesParams
758
): Promise<MetricGetBreakdownTimeseriesResponse>;
759

760
interface MetricGetBreakdownTimeseriesParams {
761
  /** Dimension to break down by */
762
  dimension?:
763
    | 'asn'
764
    | 'cdn'
765
    | 'country'
766
    | 'operating_system'
767
    | 'player_name'
768
    | 'region'
769
    | 'stream_type'
770
    | 'sub_property_id'
771
    | 'video_series'
772
    | 'video_title'
773
    | 'view_has_ad';
774
  /** Filters to apply */
775
  filters?: Array<string>;
776
  /** Number of items per timestamp (default: 10, max: 100) */
777
  limit?: number;
778
  /** Field to order results by */
779
  order_by?: 'negative_impact' | 'value' | 'views' | 'field';
780
  /** Sort order */
781
  order_direction?: 'asc' | 'desc';
782
  /** Timeframe window (last 60 seconds by default, max 10 minutes, must be within last 24 hours) */
783
  timeframe?: Array<string>;
784
}
785

786
interface MetricGetBreakdownTimeseriesResponse {
787
  /** Timeseries data points */
788
  data: Array<{
789
    /** Timestamp for this data point */
790
    date: string;
791
    /** Breakdown values at this timestamp */
792
    values: Array<{
793
      /** Number of concurrent viewers */
794
      concurrent_viewers: number;
795
      /** Calculated metric value */
796
      metric_value: number | null;
797
      /** Number of viewers in startup phase */
798
      starting_up_viewers: number;
799
      /** Dimension value */
800
      value: string | null;
801
    }>;
802
  }>;
803
  /** Applied timeframe */
804
  timeframe: Array<number>;
805
  /** Total row count */
806
  total_row_count: number | null;
807
}
808

809
/**
810
 * Get histogram timeseries data for a specific metric
811
 * @param monitoringHistogramMetricId - Monitoring histogram metric identifier
812
 * @param query - Histogram timeseries query parameters
813
 * @returns Promise resolving to histogram timeseries data
814
 */
815
getHistogramTimeseries(
816
  monitoringHistogramMetricId: 'video-startup-time',
817
  query?: MetricGetHistogramTimeseriesParams
818
): Promise<MetricGetHistogramTimeseriesResponse>;
819

820
interface MetricGetHistogramTimeseriesParams {
821
  /** Filters to apply */
822
  filters?: Array<string>;
823
}
824

825
interface MetricGetHistogramTimeseriesResponse {
826
  /** Histogram data points */
827
  data: Array<{
828
    /** Average value */
829
    average: number | null;
830
    /** Bucket values with counts and percentages */
831
    bucket_values: Array<{
832
      /** Count in this bucket */
833
      count: number;
834
      /** Percentage in this bucket */
835
      percentage: number;
836
    }>;
837
    /** Maximum percentage across buckets */
838
    max_percentage: number;
839
    /** Median value */
840
    median: number | null;
841
    /** 95th percentile value */
842
    p95: number | null;
843
    /** Sum of all values */
844
    sum: number;
845
    /** Timestamp for this data point */
846
    timestamp: string;
847
  }>;
848
  /** Metadata about histogram buckets */
849
  meta: {
850
    /** Unit for bucket measurements */
851
    bucket_unit: string;
852
    /** Bucket definitions */
853
    buckets: Array<{
854
      /** Bucket end value (null for last bucket) */
855
      end: number | null;
856
      /** Bucket start value */
857
      start: number;
858
    }>;
859
  };
860
  /** Applied timeframe */
861
  timeframe: Array<number>;
862
  /** Total row count */
863
  total_row_count: number | null;
864
}
865

866
/**
867
 * Get timeseries data for a specific monitoring metric
868
 * @param monitoringMetricId - Monitoring metric identifier
869
 * @param query - Timeseries query parameters
870
 * @returns Promise resolving to timeseries data with concurrent viewer counts
871
 */
872
getTimeseries(
873
  monitoringMetricId: MonitoringMetricId,
874
  query?: MetricGetTimeseriesParams
875
): Promise<MetricGetTimeseriesResponse>;
876

877
interface MetricGetTimeseriesParams {
878
  /** Filters to apply */
879
  filters?: Array<string>;
880
  /** Unix timestamp for start of timeseries (defaults to 30 minutes ago) */
881
  timestamp?: number;
882
}
883

884
interface MetricGetTimeseriesResponse {
885
  /** Timeseries data points */
886
  data: Array<{
887
    /** Number of concurrent viewers */
888
    concurrent_viewers: number;
889
    /** Timestamp for this data point */
890
    date: string;
891
    /** Metric value at this timestamp */
892
    value: number | null;
893
  }>;
894
  /** Applied timeframe */
895
  timeframe: Array<number>;
896
  /** Total row count */
897
  total_row_count: number | null;
898
}
899
```
900

901
**Usage Examples:**
902

903
```typescript
904
// List all available monitoring metrics
905
const metrics = await mux.data.monitoring.metrics.list();
906

907
// Get current concurrent viewers with breakdown by country
908
const breakdown = await mux.data.monitoring.metrics.getBreakdown(
909
  'current-concurrent-viewers',
910
  {
911
    dimension: 'country',
912
    order_by: 'views',
913
    order_direction: 'desc',
914
  }
915
);
916

917
// Get timeseries of rebuffering percentage
918
const timeseries = await mux.data.monitoring.metrics.getTimeseries(
919
  'current-rebuffering-percentage',
920
  {
921
    filters: ['stream_type:live'],
922
  }
923
);
924

925
// Get histogram of video startup times
926
const histogram = await mux.data.monitoring.metrics.getHistogramTimeseries(
927
  'video-startup-time',
928
  {
929
    filters: ['country:US'],
930
  }
931
);
932
```
933

934
## Types
935

936
```typescript { .api }
937
interface MetricValue {
938
  /** Metric value */
939
  value?: number;
940
  /** Metric timestamp */
941
  date?: string;
942
  /** Metric type */
943
  type?: string;
944
}
945

946
interface InsightsResponse {
947
  /** Insights data */
948
  data?: Array<InsightData>;
949
  /** Total row count */
950
  total_row_count?: number;
951
}
952

953
interface InsightData {
954
  /** Insight value */
955
  value?: number;
956
  /** Insight label */
957
  label?: string;
958
  /** Negative impact indicator */
959
  negative_impact?: boolean;
960
}
961

962
interface RealTimeDimensionsResponse {
963
  /** Available real-time dimensions */
964
  data?: Array<RealTimeDimension>;
965
}
966

967
interface RealTimeMetricsResponse {
968
  /** Available real-time metrics */
969
  data?: Array<RealTimeMetric>;
970
}
971

972
interface RealTimeBreakdownResponse {
973
  /** Breakdown data */
974
  data?: Array<RealTimeBreakdownValue>;
975
}
976

977
interface RealTimeTimeseriesResponse {
978
  /** Timeseries data points */
979
  data?: Array<RealTimeTimeseriesValue>;
980
}
981
```