Analytics and Metrics

/**
 * List all available metrics
 * @param query - Metric listing parameters
 * @returns Promise resolving to all metric values
 */
list(query?: MetricListParams): Promise<AllMetricValuesResponse>;

interface MetricListParams {
  /** Timeframe for metric data */
  timeframe?: Array<string>;
  /** Filters to apply to metrics */
  filters?: Array<string>;
  /** Dimension to break down results by */
  dimension?: string;
  /** Measurement type */
  measurement?: string;
}

interface AllMetricValuesResponse {
  /** Array of metric data points */
  data: Array<MetricValue>;
  /** Total number of data points */
  total_row_count?: number;
  /** Applied timeframe */
  timeframe?: Array<number>;
}

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

interface MetricGetInsightsParams {
  /** Timeframe for insights */
  timeframe?: Array<string>;
  /** Filters to apply */
  filters?: Array<string>;
  /** Measurement type */
  measurement?: '95th' | 'median' | 'avg' | 'count' | 'sum';
  /** Limit the results to rows that match inequality conditions */
  metric_filters?: Array<string>;
  /** Order direction */
  order_direction?: 'asc' | 'desc';
}

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

interface MetricGetOverallValuesParams {
  /** Timeframe for overall values */
  timeframe?: Array<string>;
  /** Filters to apply */
  filters?: Array<string>;
  /** Measurement type */
  measurement?: '95th' | 'median' | 'avg' | 'count' | 'sum';
  /** Limit the results to rows that match inequality conditions */
  metric_filters?: Array<string>;
}

interface OverallValuesResponse {
  /** Overall values data */
  data: OverallValuesData;
  /** Metadata */
  meta: MetricMeta;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

interface OverallValuesData {
  /** Global value for the metric */
  global_value: number | null;
  /** Total playing time */
  total_playing_time: number | null;
  /** Total views */
  total_views: number;
  /** Total watch time */
  total_watch_time: number | null;
  /** Calculated metric value */
  value: number;
}

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

interface MetricGetTimeseriesParams {
  /** Timeframe for timeseries */
  timeframe?: Array<string>;
  /** Filters to apply */
  filters?: Array<string>;
  /** Time granularity to group results by */
  group_by?: 'minute' | 'ten_minutes' | 'hour' | 'day';
  /** Measurement type */
  measurement?: '95th' | 'median' | 'avg' | 'count' | 'sum';
  /** Limit the results to rows that match inequality conditions */
  metric_filters?: Array<string>;
  /** Order direction */
  order_direction?: 'asc' | 'desc';
}

interface MetricTimeseriesDataResponse {
  /** Timeseries data points - each array contains [timestamp, metric_value, view_count] */
  data: Array<Array<string | number | null>>;
  /** Metadata */
  meta: MetricMeta;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number;
}

interface MetricMeta {
  /** Aggregation method */
  aggregation?: string;
  /** Time granularity */
  granularity?: string;
}

// Get all video views for the last 7 days
const metrics = await mux.data.metrics.list({
  timeframe: ['7:days'],
  filters: ['operating_system:Windows'],
});

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

// Get breakdown values for video quality
const breakdown = await mux.data.metrics.listBreakdownValues('video_quality_score', {
  timeframe: ['30:days'],
  dimension: 'country',
  order_direction: 'desc',
});

/**
 * List available real-time dimensions
 * @returns Promise resolving to real-time dimensions
 */
listDimensions(): Promise<RealTimeDimensionsResponse>;

/**
 * List available real-time metrics
 * @returns Promise resolving to real-time metrics
 */
listMetrics(): Promise<RealTimeMetricsResponse>;

/**
 * Retrieve real-time breakdown data
 * @param realTimeMetricId - The real-time metric identifier
 * @param query - Breakdown query parameters
 * @returns Promise resolving to real-time breakdown data
 */
retrieveBreakdown(
  realTimeMetricId: string,
  query?: RealTimeRetrieveBreakdownParams
): Promise<RealTimeBreakdownResponse>;

interface RealTimeRetrieveBreakdownParams {
  /** Dimension to break down by */
  dimension?: string;
  /** Filters to apply */
  filters?: Array<string>;
  /** Timestamp for data point */
  timestamp?: number;
  /** Order direction */
  order_direction?: 'asc' | 'desc';
  /** Order by field */
  order_by?: string;
}

/**
 * Retrieve real-time timeseries data
 * @param realTimeMetricId - The real-time metric identifier
 * @param query - Timeseries query parameters
 * @returns Promise resolving to real-time timeseries data
 */
retrieveTimeseries(
  realTimeMetricId: string,
  query?: RealTimeRetrieveTimeseriesParams
): Promise<RealTimeTimeseriesResponse>;

/**
 * List video views with filtering and pagination
 * @param query - Video view listing parameters
 * @returns Paginated list of video views
 */
list(query?: VideoViewListParams): PagePromise<AbridgedVideoViewsBasePage, AbridgedVideoView>;

interface VideoViewListParams extends BasePageParams {
  /** Filter by viewer ID */
  viewer_id?: string;
  /** Filter by error ID */
  error_id?: string;
  /** Filter by order direction */
  order_direction?: 'asc' | 'desc';
  /** Filter by asset ID */
  filters?: Array<string>;
  /** Metric filters */
  metric_filters?: Array<string>;
  /** Timeframe for views */
  timeframe?: Array<string>;
}

/**
 * Retrieve detailed video view information
 * @param videoViewId - The video view identifier
 * @returns Promise resolving to detailed video view data
 */
retrieve(videoViewId: string): Promise<VideoViewResponse>;

interface AbridgedVideoView {
  /** Video view identifier */
  id?: string;
  /** Viewer identifier */
  viewer_id?: string;
  /** Total view time in seconds */
  total_row_count?: number;
  /** Player error ID if applicable */
  player_error_id?: string;
  /** Asset ID being viewed */
  asset_id?: string;
}

interface VideoViewResponse {
  /** Detailed video view data */
  data?: VideoView;
}

interface VideoView {
  /** View session identifier */
  id?: string;
  /** Viewer identifier */
  viewer_id?: string;
  /** View session creation timestamp */
  created_at?: string;
  /** Total watch time in milliseconds */
  total_row_count?: number;
  /** Player software information */
  player_software?: string;
  /** Player software version */
  player_software_version?: string;
  /** Operating system */
  operating_system?: string;
  /** Browser name */
  browser?: string;
  /** Geographic country */
  country?: string;
  /** Asset being viewed */
  asset_id?: string;
  /** Playback ID used */
  playback_id?: string;
}

/**
 * Create a custom annotation
 * @param body - Annotation creation parameters
 * @returns Promise resolving to the created annotation
 */
create(body: AnnotationCreateParams): Promise<Annotation>;

interface AnnotationCreateParams {
  /** Datetime when the annotation applies (Unix timestamp) */
  date: number;
  /** The annotation note content */
  note: string;
  /** Customer-defined sub-property identifier */
  sub_property_id?: string;
}

interface Annotation {
  /** Unique identifier for the annotation */
  id: string;
  /** Datetime when the annotation applies */
  date: string;
  /** The annotation note content */
  note: string;
  /** Customer-defined sub-property identifier */
  sub_property_id?: string | null;
}

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

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

interface AnnotationListParams {
  /** Sort order */
  order_direction?: 'asc' | 'desc';
  /** Timeframe window to limit results */
  timeframe?: Array<string>;
  /** Page number */
  page?: number;
  /** Number of items per page */
  limit?: number;
}

/**
 * Update an existing annotation
 * @param annotationId - The annotation identifier
 * @param body - Annotation update parameters
 * @returns Promise resolving to the updated annotation
 */
update(annotationId: string, body: AnnotationUpdateParams): Promise<Annotation>;

/**
 * Delete an annotation
 * @param annotationId - The annotation identifier
 * @returns Promise that resolves when deletion is complete
 */
delete(annotationId: string): Promise<void>;

/**
 * List all available dimensions
 * @returns Promise resolving to available dimensions
 */
list(): Promise<DimensionsResponse>;

/**
 * List values for a specific dimension
 * @param dimensionId - The dimension identifier
 * @param query - Dimension value listing parameters
 * @returns Paginated list of dimension values
 */
listValues(
  dimensionId: string,
  query?: DimensionListValuesParams
): PagePromise<DimensionValuesBasePage, DimensionValue>;

interface DimensionListValuesParams extends BasePageParams {
  /** Filters to apply */
  filters?: Array<string>;
  /** Timeframe for values */
  timeframe?: Array<string>;
}

interface DimensionValue {
  /** Dimension value */
  value?: string;
  /** Total count for this value */
  total_count?: number;
}

/**
 * List available filter types
 * @returns Promise resolving to available filters
 */
listFilters(): Promise<FiltersResponse>;

/**
 * List values for a specific filter
 * @param filterId - The filter identifier
 * @param query - Filter value listing parameters
 * @returns Paginated list of filter values
 */
listFilterValues(
  filterId: string,
  query?: FilterListValuesParams
): PagePromise<FilterValuesBasePage, FilterValue>;

/**
 * List playback errors with filtering
 * @param query - Error listing parameters
 * @returns Promise resolving to error data
 */
list(query?: ErrorListParams): Promise<ErrorsResponse>;

interface ErrorListParams {
  /** Filters to apply to errors */
  filters?: Array<string>;
  /** Timeframe for errors */
  timeframe?: Array<string>;
}

interface ErrorsResponse {
  /** Array of error data */
  data: Array<ErrorData>;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total error count */
  total_row_count: number | null;
}

interface ErrorData {
  /** A unique identifier for this error */
  id: number;
  /** The error code */
  code: number | null;
  /** The total number of views that experienced this error */
  count: number;
  /** Description of the error */
  description: string | null;
  /** The last time this error was seen (ISO 8601 timestamp) */
  last_seen: string;
  /** The error message */
  message: string | null;
  /** Notes that are attached to this error */
  notes: string | null;
  /** The percentage of views that experienced this error */
  percentage: number;
  /** The string version of the error code */
  player_error_code: string | null;
}

/**
 * List service incidents
 * @param query - Incident listing parameters
 * @returns Paginated list of incidents
 */
list(query?: IncidentListParams): PagePromise<IncidentsBasePage, Incident>;

interface IncidentListParams extends BasePageParams {
  /** Value to order the results by */
  order_by?: 'negative_impact' | 'value' | 'views' | 'field';
  /** Sort order */
  order_direction?: 'asc' | 'desc';
  /** Severity to filter incidents by */
  severity?: 'warning' | 'alert';
  /** Status to filter incidents by */
  status?: 'open' | 'closed' | 'expired';
}

/**
 * Retrieve incident details
 * @param incidentId - The incident identifier
 * @returns Promise resolving to incident details
 */
retrieve(incidentId: string): Promise<Incident>;

/**
 * List related incidents
 * @param incidentId - The incident identifier
 * @param query - Related incident listing parameters
 * @returns Paginated list of related incidents
 */
listRelated(
  incidentId: string,
  query?: IncidentListRelatedParams
): PagePromise<IncidentsBasePage, Incident>;

interface Incident {
  /** Incident identifier */
  id: string;
  /** Number of affected views */
  affected_views: number;
  /** Affected views per hour */
  affected_views_per_hour: number;
  /** Affected views per hour when opened */
  affected_views_per_hour_on_open: number;
  /** Breakdown details */
  breakdowns: Array<IncidentBreakdown>;
  /** Incident description */
  description: string;
  /** Error description */
  error_description: string;
  /** Impact description */
  impact: string;
  /** Incident key */
  incident_key: string;
  /** Measured value */
  measured_value: number | null;
  /** Measured value on close */
  measured_value_on_close: number | null;
  /** Measurement type */
  measurement: string;
  /** Notification rules */
  notification_rules: Array<IncidentNotificationRule>;
  /** Notifications sent */
  notifications: Array<IncidentNotification>;
  /** Resolution timestamp */
  resolved_at: string | null;
  /** Sample size */
  sample_size: number;
  /** Sample size unit */
  sample_size_unit: string;
  /** Severity level */
  severity: string;
  /** Start timestamp */
  started_at: string;
  /** Current status */
  status: string;
  /** Threshold value */
  threshold: number;
}

interface IncidentBreakdown {
  /** Breakdown identifier */
  id: string;
  /** Breakdown name */
  name: string;
  /** Breakdown value */
  value: string;
}

interface IncidentNotificationRule {
  /** Rule identifier */
  id: string;
  /** Action type */
  action: string;
  /** Property identifier */
  property_id: string;
  /** Rule conditions */
  rules: Array<{
    id: string;
    name: string;
    value: string;
  }>;
  /** Rule status */
  status: string;
}

interface IncidentNotification {
  /** Notification identifier */
  id: number;
  /** Attempt timestamp */
  attempted_at: string;
  /** Queued timestamp */
  queued_at: string;
}

/**
 * List available video view exports
 * @returns Promise resolving to available exports
 */
listVideoViews(): Promise<VideoViewExportsResponse>;

interface VideoViewExportsResponse {
  /** Array of available exports */
  data: Array<VideoViewExport>;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

interface VideoViewExport {
  /** Export date */
  export_date: string;
  /** Export files */
  files: Array<VideoViewExportFile>;
}

interface VideoViewExportFile {
  /** File path/URL */
  path: string;
  /** File type */
  type: string;
  /** File version */
  version: number;
}

/**
 * List monitoring dimensions
 * @returns Promise resolving to monitoring dimensions
 */
listDimensions(): Promise<MonitoringListDimensionsResponse>;

interface MonitoringListDimensionsResponse {
  /** Available monitoring dimensions */
  data?: Array<MonitoringDimension>;
}

interface MonitoringDimension {
  /** Dimension identifier */
  id?: string;
  /** Dimension display name */
  name?: string;
  /** Dimension description */
  description?: string;
}

/**
 * List available monitoring metrics
 * @returns Promise resolving to list of available monitoring metrics
 */
list(): Promise<MetricListResponse>;

interface MetricListResponse {
  /** Available monitoring metrics */
  data: Array<{
    /** Display name for the metric */
    display_name: string;
    /** Metric identifier */
    name: string;
  }>;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

/**
 * Get breakdown information for a specific dimension and metric
 * @param monitoringMetricId - Monitoring metric identifier
 * @param query - Breakdown query parameters
 * @returns Promise resolving to breakdown data with concurrent viewers and negative impact scores
 */
getBreakdown(
  monitoringMetricId: MonitoringMetricId,
  query?: MetricGetBreakdownParams
): Promise<MetricGetBreakdownResponse>;

type MonitoringMetricId =
  | 'current-concurrent-viewers'
  | 'current-rebuffering-percentage'
  | 'exits-before-video-start'
  | 'playback-failure-percentage'
  | 'current-average-bitrate'
  | 'video-startup-failure-percentage';

interface MetricGetBreakdownParams {
  /** Dimension to break down by */
  dimension?:
    | 'asn'
    | 'cdn'
    | 'country'
    | 'operating_system'
    | 'player_name'
    | 'region'
    | 'stream_type'
    | 'sub_property_id'
    | 'video_series'
    | 'video_title'
    | 'view_has_ad';
  /** Filters to apply (e.g., 'operating_system:windows', '!country:US') */
  filters?: Array<string>;
  /** Field to order results by */
  order_by?: 'negative_impact' | 'value' | 'views' | 'field';
  /** Sort order */
  order_direction?: 'asc' | 'desc';
  /** Unix timestamp to limit results (defaults to current time) */
  timestamp?: number;
}

interface MetricGetBreakdownResponse {
  /** Breakdown data points */
  data: Array<{
    /** Number of concurrent viewers */
    concurrent_viewers: number;
    /** Calculated metric value */
    metric_value: number | null;
    /** Negative impact score */
    negative_impact: number;
    /** Number of viewers in startup phase */
    starting_up_viewers: number;
    /** Dimension value */
    value: string | null;
    /** Human-readable display value */
    display_value?: string;
  }>;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

/**
 * Get timeseries of breakdown information for a specific dimension and metric
 * @param monitoringMetricId - Monitoring metric identifier
 * @param query - Breakdown timeseries query parameters
 * @returns Promise resolving to timeseries breakdown data (5-second intervals)
 */
getBreakdownTimeseries(
  monitoringMetricId: MonitoringMetricId,
  query?: MetricGetBreakdownTimeseriesParams
): Promise<MetricGetBreakdownTimeseriesResponse>;

interface MetricGetBreakdownTimeseriesParams {
  /** Dimension to break down by */
  dimension?:
    | 'asn'
    | 'cdn'
    | 'country'
    | 'operating_system'
    | 'player_name'
    | 'region'
    | 'stream_type'
    | 'sub_property_id'
    | 'video_series'
    | 'video_title'
    | 'view_has_ad';
  /** Filters to apply */
  filters?: Array<string>;
  /** Number of items per timestamp (default: 10, max: 100) */
  limit?: number;
  /** Field to order results by */
  order_by?: 'negative_impact' | 'value' | 'views' | 'field';
  /** Sort order */
  order_direction?: 'asc' | 'desc';
  /** Timeframe window (last 60 seconds by default, max 10 minutes, must be within last 24 hours) */
  timeframe?: Array<string>;
}

interface MetricGetBreakdownTimeseriesResponse {
  /** Timeseries data points */
  data: Array<{
    /** Timestamp for this data point */
    date: string;
    /** Breakdown values at this timestamp */
    values: Array<{
      /** Number of concurrent viewers */
      concurrent_viewers: number;
      /** Calculated metric value */
      metric_value: number | null;
      /** Number of viewers in startup phase */
      starting_up_viewers: number;
      /** Dimension value */
      value: string | null;
    }>;
  }>;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

/**
 * Get histogram timeseries data for a specific metric
 * @param monitoringHistogramMetricId - Monitoring histogram metric identifier
 * @param query - Histogram timeseries query parameters
 * @returns Promise resolving to histogram timeseries data
 */
getHistogramTimeseries(
  monitoringHistogramMetricId: 'video-startup-time',
  query?: MetricGetHistogramTimeseriesParams
): Promise<MetricGetHistogramTimeseriesResponse>;

interface MetricGetHistogramTimeseriesParams {
  /** Filters to apply */
  filters?: Array<string>;
}

interface MetricGetHistogramTimeseriesResponse {
  /** Histogram data points */
  data: Array<{
    /** Average value */
    average: number | null;
    /** Bucket values with counts and percentages */
    bucket_values: Array<{
      /** Count in this bucket */
      count: number;
      /** Percentage in this bucket */
      percentage: number;
    }>;
    /** Maximum percentage across buckets */
    max_percentage: number;
    /** Median value */
    median: number | null;
    /** 95th percentile value */
    p95: number | null;
    /** Sum of all values */
    sum: number;
    /** Timestamp for this data point */
    timestamp: string;
  }>;
  /** Metadata about histogram buckets */
  meta: {
    /** Unit for bucket measurements */
    bucket_unit: string;
    /** Bucket definitions */
    buckets: Array<{
      /** Bucket end value (null for last bucket) */
      end: number | null;
      /** Bucket start value */
      start: number;
    }>;
  };
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

/**
 * Get timeseries data for a specific monitoring metric
 * @param monitoringMetricId - Monitoring metric identifier
 * @param query - Timeseries query parameters
 * @returns Promise resolving to timeseries data with concurrent viewer counts
 */
getTimeseries(
  monitoringMetricId: MonitoringMetricId,
  query?: MetricGetTimeseriesParams
): Promise<MetricGetTimeseriesResponse>;

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

interface MetricGetTimeseriesResponse {
  /** Timeseries data points */
  data: Array<{
    /** Number of concurrent viewers */
    concurrent_viewers: number;
    /** Timestamp for this data point */
    date: string;
    /** Metric value at this timestamp */
    value: number | null;
  }>;
  /** Applied timeframe */
  timeframe: Array<number>;
  /** Total row count */
  total_row_count: number | null;
}

// List all available monitoring metrics
const metrics = await mux.data.monitoring.metrics.list();

// Get current concurrent viewers with breakdown by country
const breakdown = await mux.data.monitoring.metrics.getBreakdown(
  'current-concurrent-viewers',
  {
    dimension: 'country',
    order_by: 'views',
    order_direction: 'desc',
  }
);

// Get timeseries of rebuffering percentage
const timeseries = await mux.data.monitoring.metrics.getTimeseries(
  'current-rebuffering-percentage',
  {
    filters: ['stream_type:live'],
  }
);

// Get histogram of video startup times
const histogram = await mux.data.monitoring.metrics.getHistogramTimeseries(
  'video-startup-time',
  {
    filters: ['country:US'],
  }
);

interface MetricValue {
  /** Metric value */
  value?: number;
  /** Metric timestamp */
  date?: string;
  /** Metric type */
  type?: string;
}

interface InsightsResponse {
  /** Insights data */
  data?: Array<InsightData>;
  /** Total row count */
  total_row_count?: number;
}

interface InsightData {
  /** Insight value */
  value?: number;
  /** Insight label */
  label?: string;
  /** Negative impact indicator */
  negative_impact?: boolean;
}

interface RealTimeDimensionsResponse {
  /** Available real-time dimensions */
  data?: Array<RealTimeDimension>;
}

interface RealTimeMetricsResponse {
  /** Available real-time metrics */
  data?: Array<RealTimeMetric>;
}

interface RealTimeBreakdownResponse {
  /** Breakdown data */
  data?: Array<RealTimeBreakdownValue>;
}

interface RealTimeTimeseriesResponse {
  /** Timeseries data points */
  data?: Array<RealTimeTimeseriesValue>;
}