Delivery Usage

/**
 * List delivery usage records for assets and live streams
 * @param query - Optional filtering and pagination parameters
 * @returns PagePromise for iterating through delivery reports
 */
list(
  query?: DeliveryUsageListParams,
  options?: Core.RequestOptions
): Core.PagePromise<DeliveryReportsPageWithTotal, DeliveryReport>;

interface DeliveryUsageListParams extends PageWithTotalParams {
  /** Filter by specific asset ID (mutually exclusive with live_stream_id) */
  asset_id?: string;
  /** Filter by live stream ID (mutually exclusive with asset_id) */
  live_stream_id?: string;
  /** Time window as [start_time, end_time] in Unix seconds */
  timeframe?: Array<string>;
  /** Page number for pagination */
  page?: number;
  /** Number of items per page */
  limit?: number;
}

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

const mux = new Mux({
  tokenId: process.env.MUX_TOKEN_ID,
  tokenSecret: process.env.MUX_TOKEN_SECRET,
});

// Get delivery usage for all assets (last hour by default)
for await (const report of mux.video.deliveryUsage.list()) {
  console.log(`Asset ${report.asset_id}: ${report.delivered_seconds} seconds delivered`);
  console.log(`Resolution breakdown:`, report.delivered_seconds_by_resolution);
}

// Get delivery usage for specific asset
const assetUsage = await mux.video.deliveryUsage.list({
  asset_id: "ASSET_ID"
});

for await (const report of assetUsage) {
  console.log(`Delivered seconds: ${report.delivered_seconds}`);
  console.log(`Asset duration: ${report.asset_duration} seconds`);
  console.log(`Video quality: ${report.asset_video_quality}`);
}

// Get delivery usage for specific live stream
const liveStreamUsage = await mux.video.deliveryUsage.list({
  live_stream_id: "LIVE_STREAM_ID"
});

for await (const report of liveStreamUsage) {
  console.log(`Live stream ${report.live_stream_id} delivery: ${report.delivered_seconds} seconds`);
}

// Get delivery usage for custom time window (last 24 hours)
const yesterday = Math.floor((Date.now() - 24 * 60 * 60 * 1000) / 1000);
const now = Math.floor(Date.now() / 1000);

const customTimeframeUsage = await mux.video.deliveryUsage.list({
  timeframe: [yesterday.toString(), now.toString()]
});

for await (const report of customTimeframeUsage) {
  console.log(`24h delivery for ${report.asset_id}: ${report.delivered_seconds} seconds`);
}

interface DeliveryReport {
  /** Duration of the asset in seconds */
  asset_duration: number;
  /** @deprecated Use asset_video_quality instead */
  asset_encoding_tier: 'smart' | 'baseline' | 'premium';
  /** Unique identifier for the asset */
  asset_id: string;
  /** Resolution tier for billing (ingest & storage) */
  asset_resolution_tier: 'audio-only' | '720p' | '1080p' | '1440p' | '2160p';
  /** Current state of the asset */
  asset_state: 'ready' | 'errored' | 'deleted';
  /** Asset creation timestamp (Unix seconds since epoch) */
  created_at: string;
  /** Total delivered seconds in this time window */
  delivered_seconds: number;
  /** Delivery breakdown by resolution tier */
  delivered_seconds_by_resolution: DeliveredSecondsByResolution;
  /** Video quality level (replaces asset_encoding_tier) */
  asset_video_quality?: 'basic' | 'plus' | 'premium';
  /** Asset deletion timestamp if deleted */
  deleted_at?: string;
  /** Live stream ID that created this asset */
  live_stream_id?: string;
  /** Asset passthrough metadata */
  passthrough?: string;
}

interface DeliveredSecondsByResolution {
  /** Audio-only delivery seconds */
  tier_audio_only?: number;
  /** 720p tier delivery seconds (up to 921,600 pixels) */
  tier_720p?: number;
  /** 1080p tier delivery seconds (921,600 to 2,073,600 pixels) */
  tier_1080p?: number;
  /** 1440p tier delivery seconds (2,073,600 to 4,194,304 pixels) */
  tier_1440p?: number;
  /** 2160p+ tier delivery seconds (over 4,194,304 pixels) */
  tier_2160p?: number;
}

/** Pagination wrapper for delivery reports with total count */
class DeliveryReportsPageWithTotal extends PageWithTotal<DeliveryReport> {}

const assetReports = await mux.video.deliveryUsage.list({
  asset_id: "ASSET_ID"
});

const liveStreamReports = await mux.video.deliveryUsage.list({
  live_stream_id: "LIVE_STREAM_ID"
});

// Last 7 days
const weekAgo = Math.floor((Date.now() - 7 * 24 * 60 * 60 * 1000) / 1000);
const now = Math.floor(Date.now() / 1000);

const weeklyReports = await mux.video.deliveryUsage.list({
  timeframe: [weekAgo.toString(), now.toString()]
});

// Calculate total bandwidth usage
let totalSeconds = 0;
let tierBreakdown = {
  audio: 0,
  '720p': 0,
  '1080p': 0,
  '1440p': 0,
  '2160p': 0
};

for await (const report of mux.video.deliveryUsage.list()) {
  totalSeconds += report.delivered_seconds;

  const breakdown = report.delivered_seconds_by_resolution;
  tierBreakdown.audio += breakdown.tier_audio_only || 0;
  tierBreakdown['720p'] += breakdown.tier_720p || 0;
  tierBreakdown['1080p'] += breakdown.tier_1080p || 0;
  tierBreakdown['1440p'] += breakdown.tier_1440p || 0;
  tierBreakdown['2160p'] += breakdown.tier_2160p || 0;
}

console.log(`Total delivery: ${totalSeconds} seconds`);
console.log('Tier breakdown:', tierBreakdown);

// Get delivery usage alongside view metrics
const [deliveryReports, viewReports] = await Promise.all([
  mux.video.deliveryUsage.list().autoPaginate(),
  mux.data.videoViews.list().autoPaginate()
]);

// Correlate delivery and viewing patterns
const correlatedData = deliveryReports.map(delivery => {
  const relatedViews = viewReports.filter(view => view.asset_id === delivery.asset_id);
  return {
    asset_id: delivery.asset_id,
    delivered_seconds: delivery.delivered_seconds,
    view_count: relatedViews.length,
    average_view_duration: relatedViews.reduce((sum, v) => sum + (v.view_total_content_playback_time || 0), 0) / relatedViews.length
  };
});