CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-mux--mux-node

Official TypeScript library providing comprehensive client access to Mux's video infrastructure API including asset management, live streaming, analytics, and webhook handling

Overview
Eval results
Files

data.mddocs/

Data Module

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.

Imports

import Mux from '@mux/mux-node';

const client = new Mux({
  tokenId: 'YOUR_TOKEN_ID',
  tokenSecret: 'YOUR_TOKEN_SECRET',
});

// Access data resources
const metrics = client.data.metrics;
const videoViews = client.data.videoViews;
const incidents = client.data.incidents;

Capabilities

Metrics

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

interface Metrics {
  /**
   * List available metrics
   */
  list(query?: MetricListParams, options?: RequestOptions): Promise<AllMetricValuesResponse>;

  /**
   * Get overall metric values
   */
  getOverallValues(
    metricId: string,
    query?: MetricGetOverallValuesParams,
    options?: RequestOptions
  ): Promise<OverallValuesResponse>;

  /**
   * Get metric timeseries data
   */
  getTimeseries(
    metricId: string,
    query?: MetricGetTimeseriesParams,
    options?: RequestOptions
  ): Promise<MetricTimeseriesDataResponse>;

  /**
   * Get metric breakdown by dimension
   */
  listBreakdownValues(
    metricId: string,
    query?: MetricListBreakdownValuesParams,
    options?: RequestOptions
  ): PagePromise<BreakdownValuesBasePage, BreakdownValue>;

  /**
   * Get metric insights and recommendations
   */
  getInsights(
    metricId: string,
    query?: MetricGetInsightsParams,
    options?: RequestOptions
  ): Promise<InsightsResponse>;
}

interface MetricGetOverallValuesParams {
  /** Time range [start, end] */
  timeframe?: Array<string>;
  /** Filter conditions */
  filters?: Array<string>;
  /** Measurement type */
  measurement?: string;
}

interface MetricGetTimeseriesParams {
  /** Time range [start, end] */
  timeframe?: Array<string>;
  /** Filter conditions */
  filters?: Array<string>;
  /** Measurement type */
  measurement?: string;
  /** Sort direction ('asc', 'desc') */
  order_direction?: 'asc' | 'desc';
}

interface MetricListBreakdownValuesParams {
  /** Dimension to group by */
  group_by?: string;
  /** Time range [start, end] */
  timeframe?: Array<string>;
  /** Filter conditions */
  filters?: Array<string>;
  /** Measurement type */
  measurement?: string;
  /** Sort field */
  order_by?: string;
  /** Sort direction ('asc', 'desc') */
  order_direction?: 'asc' | 'desc';
  /** Items per page */
  limit?: number;
}

interface BreakdownValue {
  /** Dimension value */
  value: string;
  /** Total count */
  total_count?: number;
  /** Field name */
  field?: string;
  /** View count */
  views?: number;
  /** Negative impact score */
  negative_impact?: number;
}

Usage Example:

// Get overall metric values
const metrics = await client.data.metrics.getOverallValues('video_startup_time', {
  timeframe: ['7:days'],
  filters: ['asset_id:ASSET_ID'],
});

// Get metric breakdown by browser
const breakdown = await client.data.metrics.listBreakdownValues('video_startup_time', {
  group_by: 'browser',
  timeframe: ['7:days'],
  filters: ['asset_id:ASSET_ID'],
  limit: 10,
});

Real-Time Analytics

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

interface RealTime {
  /**
   * List available real-time dimensions
   */
  listDimensions(options?: RequestOptions): Promise<RealTimeDimensionsResponse>;

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

  /**
   * Get real-time metric breakdown
   */
  retrieveBreakdown(
    realtimeMetricId: string,
    query?: RealTimeRetrieveBreakdownParams,
    options?: RequestOptions
  ): Promise<RealTimeBreakdownResponse>;

  /**
   * Get real-time metric timeseries
   */
  retrieveTimeseries(
    realtimeMetricId: string,
    query?: RealTimeRetrieveTimeseriesParams,
    options?: RequestOptions
  ): Promise<RealTimeTimeseriesResponse>;

  /**
   * Get real-time histogram timeseries
   */
  retrieveHistogramTimeseries(
    realtimeHistogramMetricId: string,
    query?: RealTimeRetrieveHistogramTimeseriesParams,
    options?: RequestOptions
  ): Promise<RealTimeHistogramTimeseriesResponse>;
}

interface RealTimeRetrieveBreakdownParams {
  /** Dimension to group by */
  dimension?: string;
  /** Filter conditions */
  filters?: Array<string>;
  /** Sort field */
  order_by?: string;
  /** Sort direction ('asc', 'desc') */
  order_direction?: 'asc' | 'desc';
  /** Unix timestamp */
  timestamp?: number;
}

interface RealTimeRetrieveTimeseriesParams {
  /** Filter conditions */
  filters?: Array<string>;
  /** Unix timestamp */
  timestamp?: number;
}

Usage Example:

// Get current concurrent viewers
const breakdown = await client.data.realTime.retrieveBreakdown('current-concurrent-viewers', {
  dimension: 'assetId',
  filters: ['asset_id:ASSET_ID'],
});

Video Views

Query individual video view session data.

interface VideoViews {
  /**
   * Retrieve detailed video view data
   */
  retrieve(viewId: string, options?: RequestOptions): Promise<VideoViewResponse>;

  /**
   * List video views
   */
  list(query?: VideoViewListParams, options?: RequestOptions): PagePromise<AbridgedVideoViewsBasePage, AbridgedVideoView>;
}

interface VideoViewListParams {
  /** Items per page */
  limit?: number;
  /** Page number */
  page?: number;
  /** Filter by viewer ID */
  viewer_id?: string;
  /** Filter by error ID */
  error_id?: string;
  /** Sort direction ('asc', 'desc') */
  order_direction?: 'asc' | 'desc';
  /** Filter conditions */
  filters?: Array<string>;
  /** Time range [start, end] */
  timeframe?: Array<string>;
}

interface AbridgedVideoView {
  /** View identifier */
  id: string;
  /** Viewer OS */
  viewer_os_family?: string;
  /** Device name */
  viewer_device_name?: string;
  /** Application name */
  viewer_application_name?: string;
  /** Video title */
  video_title?: string;
  /** Total views */
  total_row_count?: number;
  /** View timestamp */
  created_at?: string;
  /** Start timestamp */
  view_start?: string;
  /** End timestamp */
  view_end?: string;
  /** Watch time in milliseconds */
  watched_time?: number;
  /** Player instance ID */
  player_instance_id?: string;
}

Usage Example:

// List video views for an asset
const views = await client.data.videoViews.list({
  filters: ['asset_id:ASSET_ID'],
  timeframe: ['7:days'],
  limit: 100,
});

for await (const view of views) {
  console.log(view.id, view.watched_time);
}

Incidents

Track and manage playback incidents.

interface Incidents {
  /**
   * Retrieve incident details
   */
  retrieve(incidentId: string, options?: RequestOptions): Promise<Incident>;

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

  /**
   * List related incidents
   */
  listRelated(
    incidentId: string,
    query?: IncidentListRelatedParams,
    options?: RequestOptions
  ): PagePromise<IncidentsBasePage, Incident>;
}

interface IncidentListParams {
  /** Items per page */
  limit?: number;
  /** Page number */
  page?: number;
  /** Sort order */
  order_by?: string;
  /** Sort direction ('asc', 'desc') */
  order_direction?: 'asc' | 'desc';
  /** Filter by status ('open', 'resolved') */
  status?: 'open' | 'resolved';
  /** Filter by severity ('warning', 'alert') */
  severity?: 'warning' | 'alert';
}

interface Incident {
  /** Unique identifier */
  id: string;
  /** Incident status ('open', 'resolved') */
  status: 'open' | 'resolved';
  /** Severity level ('warning', 'alert') */
  severity: 'warning' | 'alert';
  /** Start timestamp */
  started_at?: string;
  /** Resolution timestamp */
  resolved_at?: string;
  /** Incident description */
  description?: string;
  /** Number of affected views */
  affected_views?: number;
  /** Breakdown data */
  breakdowns?: Array<object>;
  /** Error details */
  error_description?: string;
  /** Measurement data */
  measurement?: object;
}

Dimensions

Query available dimension values for filtering analytics data.

interface Dimensions {
  /**
   * List available dimensions
   */
  list(options?: RequestOptions): Promise<DimensionsResponse>;

  /**
   * List values for a specific dimension
   */
  listValues(
    dimensionId: string,
    query?: DimensionListValuesParams,
    options?: RequestOptions
  ): PagePromise<DimensionValuesBasePage, DimensionValue>;

  /**
   * List trace elements for debugging
   */
  listTraceElements(
    dimensionId: string,
    query?: DimensionListTraceElementsParams,
    options?: RequestOptions
  ): PagePromise<DimensionValuesBasePage, DimensionValue>;
}

interface DimensionListValuesParams {
  /** Items per page */
  limit?: number;
  /** Page number */
  page?: number;
  /** Filter conditions */
  filters?: Array<string>;
  /** Time range */
  timeframe?: Array<string>;
}

interface DimensionsResponse {
  /** Available dimensions */
  data?: {
    /** Basic dimensions */
    basic?: Array<string>;
    /** Advanced dimensions */
    advanced?: Array<string>;
  };
}

interface DimensionValue {
  /** Dimension value */
  value: string;
  /** Display-friendly value */
  display_value?: string;
  /** Total occurrences */
  total_count?: number;
}

Filters

Query available filter values.

interface Filters {
  /**
   * List available filters
   */
  list(options?: RequestOptions): Promise<FiltersResponse>;

  /**
   * List values for a specific filter
   */
  listValues(
    filterId: string,
    query?: FilterListValuesParams,
    options?: RequestOptions
  ): PagePromise<FilterValuesBasePage, FilterValue>;
}

interface FilterListValuesParams {
  /** Items per page */
  limit?: number;
  /** Page number */
  page?: number;
  /** Additional filters */
  filters?: Array<string>;
  /** Time range */
  timeframe?: Array<string>;
}

interface FilterValue {
  /** Filter value */
  value: string;
  /** Display-friendly value */
  display_value?: string;
  /** Total occurrences */
  total_count?: number;
}

Errors

Query playback error data.

interface Errors {
  /**
   * List error occurrences
   */
  list(query?: ErrorListParams, options?: RequestOptions): Promise<ErrorsResponse>;
}

interface ErrorListParams {
  /** Filter conditions */
  filters?: Array<string>;
  /** Time range */
  timeframe?: Array<string>;
}

Exports

Export analytics data.

interface Exports {
  /**
   * List available video view data exports
   */
  listVideoViews(options?: RequestOptions): Promise<VideoViewExportsResponse>;
}

Monitoring

Monitoring and alerting metrics.

interface Monitoring {
  /**
   * List available monitoring dimensions
   */
  listDimensions(options?: RequestOptions): Promise<MonitoringListDimensionsResponse>;

  /** Access monitoring metrics */
  metrics: MonitoringMetrics;
}

interface MonitoringMetrics {
  /**
   * List available monitoring metrics
   */
  list(options?: RequestOptions): Promise<MetricListResponse>;

  /**
   * Get breakdown information for a specific dimension and metric
   */
  getBreakdown(
    monitoringMetricId:
      | 'current-concurrent-viewers'
      | 'current-rebuffering-percentage'
      | 'exits-before-video-start'
      | 'playback-failure-percentage'
      | 'current-average-bitrate'
      | 'video-startup-failure-percentage',
    query?: MetricGetBreakdownParams,
    options?: RequestOptions
  ): Promise<MetricGetBreakdownResponse>;

  /**
   * Get timeseries of breakdown information for a specific dimension and metric
   */
  getBreakdownTimeseries(
    monitoringMetricId:
      | 'current-concurrent-viewers'
      | 'current-rebuffering-percentage'
      | 'exits-before-video-start'
      | 'playback-failure-percentage'
      | 'current-average-bitrate'
      | 'video-startup-failure-percentage',
    query?: MetricGetBreakdownTimeseriesParams,
    options?: RequestOptions
  ): Promise<MetricGetBreakdownTimeseriesResponse>;

  /**
   * Get histogram timeseries information for a specific metric
   */
  getHistogramTimeseries(
    monitoringHistogramMetricId: 'video-startup-time',
    query?: MetricGetHistogramTimeseriesParams,
    options?: RequestOptions
  ): Promise<MetricGetHistogramTimeseriesResponse>;

  /**
   * Get timeseries data for a specific monitoring metric
   */
  getTimeseries(
    monitoringMetricId:
      | 'current-concurrent-viewers'
      | 'current-rebuffering-percentage'
      | 'exits-before-video-start'
      | 'playback-failure-percentage'
      | 'current-average-bitrate'
      | 'video-startup-failure-percentage',
    query?: MetricGetTimeseriesParams,
    options?: RequestOptions
  ): Promise<MetricGetTimeseriesResponse>;
}

Analytics and Metrics Documentation

Annotations

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

interface Annotations {
  /**
   * Create a new annotation
   */
  create(body: AnnotationCreateParams, options?: RequestOptions): Promise<Annotation>;

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

  /**
   * Update annotation
   */
  update(
    annotationId: string,
    body: AnnotationUpdateParams,
    options?: RequestOptions
  ): Promise<Annotation>;

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

  /**
   * Delete annotation
   */
  delete(annotationId: string, options?: RequestOptions): Promise<void>;
}

interface AnnotationCreateParams {
  /** Annotation text */
  value: string;
  /** Event timestamp */
  timestamp: string;
}

interface Annotation {
  /** Unique identifier */
  id: string;
  /** Annotation text */
  value: string;
  /** Event timestamp */
  timestamp: string;
  /** Creation timestamp */
  created_at: string;
  /** Last update timestamp */
  updated_at?: string;
}

interface AnnotationUpdateParams {
  /** Updated annotation text */
  value?: string;
  /** Updated timestamp */
  timestamp?: string;
}

interface AnnotationListParams {
  /** Items per page */
  limit?: number;
  /** Page number */
  page?: number;
}

Usage Example:

// Create an annotation for a deployment
const annotation = await client.data.annotations.create({
  value: 'Deployed version 2.0',
  timestamp: new Date().toISOString(),
});

Common Patterns

Filtering

Filters use a key:value format to filter analytics data:

// Filter by asset ID
filters: ['asset_id:ASSET_ID']

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

// Filter by multiple values (OR logic)
filters: ['country:US,CA,GB']

Timeframes

Timeframes specify the time range for queries:

// Relative timeframe
timeframe: ['7:days']  // Last 7 days
timeframe: ['24:hours'] // Last 24 hours

// Absolute timeframe
timeframe: ['2024-01-01T00:00:00Z', '2024-01-31T23:59:59Z']

Pagination

All list endpoints support pagination:

// Manual pagination
const page1 = await client.data.videoViews.list({ limit: 100, page: 1 });
const page2 = await client.data.videoViews.list({ limit: 100, page: 2 });

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

Install with Tessl CLI

npx tessl i tessl/npm-mux--mux-node

docs

analytics-metrics.md

client-setup.md

data.md

delivery-usage.md

error-handling.md

index.md

jwt-signing.md

jwt.md

live-streaming.md

playback-control.md

system-operations.md

system.md

transcription-vocabularies.md

upload-utilities.md

video-assets.md

video-playback.md

video-uploads.md

video.md

web-inputs.md

webhooks.md

tile.json