0
# Delivery Usage
1

2
Video delivery usage and bandwidth reporting for assets and live streams. Provides detailed consumption metrics broken down by resolution tiers for billing and analytics purposes.
3

4
## Capabilities
5

6
### Delivery Usage Reporting
7

8
Retrieve delivery usage reports with detailed bandwidth consumption metrics.
9

10
```typescript { .api }
11
/**
12
 * List delivery usage records for assets and live streams
13
 * @param query - Optional filtering and pagination parameters
14
 * @returns PagePromise for iterating through delivery reports
15
 */
16
list(
17
  query?: DeliveryUsageListParams,
18
  options?: Core.RequestOptions
19
): Core.PagePromise<DeliveryReportsPageWithTotal, DeliveryReport>;
20

21
interface DeliveryUsageListParams extends PageWithTotalParams {
22
  /** Filter by specific asset ID (mutually exclusive with live_stream_id) */
23
  asset_id?: string;
24
  /** Filter by live stream ID (mutually exclusive with asset_id) */
25
  live_stream_id?: string;
26
  /** Time window as [start_time, end_time] in Unix seconds */
27
  timeframe?: Array<string>;
28
  /** Page number for pagination */
29
  page?: number;
30
  /** Number of items per page */
31
  limit?: number;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import Mux from "@mux/mux-node";
39

40
const mux = new Mux({
41
  tokenId: process.env.MUX_TOKEN_ID,
42
  tokenSecret: process.env.MUX_TOKEN_SECRET,
43
});
44

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

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

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

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

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

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

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

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

84
## Types
85

86
```typescript { .api }
87
interface DeliveryReport {
88
  /** Duration of the asset in seconds */
89
  asset_duration: number;
90
  /** @deprecated Use asset_video_quality instead */
91
  asset_encoding_tier: 'smart' | 'baseline' | 'premium';
92
  /** Unique identifier for the asset */
93
  asset_id: string;
94
  /** Resolution tier for billing (ingest & storage) */
95
  asset_resolution_tier: 'audio-only' | '720p' | '1080p' | '1440p' | '2160p';
96
  /** Current state of the asset */
97
  asset_state: 'ready' | 'errored' | 'deleted';
98
  /** Asset creation timestamp (Unix seconds since epoch) */
99
  created_at: string;
100
  /** Total delivered seconds in this time window */
101
  delivered_seconds: number;
102
  /** Delivery breakdown by resolution tier */
103
  delivered_seconds_by_resolution: DeliveredSecondsByResolution;
104
  /** Video quality level (replaces asset_encoding_tier) */
105
  asset_video_quality?: 'basic' | 'plus' | 'premium';
106
  /** Asset deletion timestamp if deleted */
107
  deleted_at?: string;
108
  /** Live stream ID that created this asset */
109
  live_stream_id?: string;
110
  /** Asset passthrough metadata */
111
  passthrough?: string;
112
}
113

114
interface DeliveredSecondsByResolution {
115
  /** Audio-only delivery seconds */
116
  tier_audio_only?: number;
117
  /** 720p tier delivery seconds (up to 921,600 pixels) */
118
  tier_720p?: number;
119
  /** 1080p tier delivery seconds (921,600 to 2,073,600 pixels) */
120
  tier_1080p?: number;
121
  /** 1440p tier delivery seconds (2,073,600 to 4,194,304 pixels) */
122
  tier_1440p?: number;
123
  /** 2160p+ tier delivery seconds (over 4,194,304 pixels) */
124
  tier_2160p?: number;
125
}
126

127
/** Pagination wrapper for delivery reports with total count */
128
class DeliveryReportsPageWithTotal extends PageWithTotal<DeliveryReport> {}
129
```
130

131
## Resolution Tier Breakdown
132

133
Delivery usage is broken down by resolution tiers based on total pixel count:
134

135
| Tier | Resolution Range | Pixel Count | Typical Resolutions |
136
|------|------------------|-------------|-------------------|
137
| Audio Only | N/A | 0 | Audio-only content |
138
| 720p | Up to 720p | ≤ 921,600 | 1280x720, 960x720 |
139
| 1080p | 720p to 1080p | 921,601 - 2,073,600 | 1920x1080, 1440x1080 |
140
| 1440p | 1080p to 1440p | 2,073,601 - 4,194,304 | 2560x1440, 2048x1440 |
141
| 2160p+ | Above 1440p | > 4,194,304 | 3840x2160 (4K), higher |
142
143
## Filtering Options
144

145
### By Asset
146
```typescript
147
const assetReports = await mux.video.deliveryUsage.list({
148
  asset_id: "ASSET_ID"
149
});
150
```
151

152
### By Live Stream
153
```typescript
154
const liveStreamReports = await mux.video.deliveryUsage.list({
155
  live_stream_id: "LIVE_STREAM_ID"
156
});
157
```
158

159
### By Time Window
160
```typescript
161
// Last 7 days
162
const weekAgo = Math.floor((Date.now() - 7 * 24 * 60 * 60 * 1000) / 1000);
163
const now = Math.floor(Date.now() / 1000);
164

165
const weeklyReports = await mux.video.deliveryUsage.list({
166
  timeframe: [weekAgo.toString(), now.toString()]
167
});
168
```
169

170
## Billing Integration
171

172
Delivery usage reports provide data for understanding bandwidth costs:
173

174
```typescript
175
// Calculate total bandwidth usage
176
let totalSeconds = 0;
177
let tierBreakdown = {
178
  audio: 0,
179
  '720p': 0,
180
  '1080p': 0,
181
  '1440p': 0,
182
  '2160p': 0
183
};
184

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

188
  const breakdown = report.delivered_seconds_by_resolution;
189
  tierBreakdown.audio += breakdown.tier_audio_only || 0;
190
  tierBreakdown['720p'] += breakdown.tier_720p || 0;
191
  tierBreakdown['1080p'] += breakdown.tier_1080p || 0;
192
  tierBreakdown['1440p'] += breakdown.tier_1440p || 0;
193
  tierBreakdown['2160p'] += breakdown.tier_2160p || 0;
194
}
195

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

200
## Analytics Integration
201

202
Combine delivery usage with other Mux Data metrics for comprehensive reporting:
203

204
```typescript
205
// Get delivery usage alongside view metrics
206
const [deliveryReports, viewReports] = await Promise.all([
207
  mux.video.deliveryUsage.list().autoPaginate(),
208
  mux.data.videoViews.list().autoPaginate()
209
]);
210

211
// Correlate delivery and viewing patterns
212
const correlatedData = deliveryReports.map(delivery => {
213
  const relatedViews = viewReports.filter(view => view.asset_id === delivery.asset_id);
214
  return {
215
    asset_id: delivery.asset_id,
216
    delivered_seconds: delivery.delivered_seconds,
217
    view_count: relatedViews.length,
218
    average_view_duration: relatedViews.reduce((sum, v) => sum + (v.view_total_content_playback_time || 0), 0) / relatedViews.length
219
  };
220
});
221
```
222

223
## Best Practices
224

225
- **Time Windows**: Use appropriate time windows to balance detail and performance
226
- **Filtering**: Filter by asset_id or live_stream_id when analyzing specific content
227
- **Pagination**: Use auto-pagination for large result sets to avoid memory issues
228
- **Tier Analysis**: Analyze resolution tier breakdown to optimize encoding strategies
229
- **Regular Monitoring**: Set up regular reporting for bandwidth usage tracking