This guide covers migration for streams using the following MSL4 archive modes:

• Basic Archive – Event Purge Mode
• Unlimited Archive Mode

Archive functionality in MSL5 works differently than MSL4, requiring advance planning and preparation.

🚧

MSL5 archive export requires active setup and management within a limited retention window. Unlike MSL4, where content is stored and accessible directly, MSL5 requires users to proactively clip and export events to Akamai Linode Object Storage.

What's Different: MSL4 vs. MSL5 Archive Workflows

MSL4 Archive Workflow (Current)

• Stream content is stored automatically on Akamai Netstorage.
• Archived content is accessible during the retention period.
• Archive retention: Configured per stream or events within the stream.

MSL5 Archive Workflow (New)

• Users manage storage (Linode Object Storage).
• Events must be manually clipped during the archive retention window.
• Clipped events are exported to selected Linode object storage.
• Users must actively export before retention expires.
• Archive retention: 62 days maximum.
• Action required: Set up Linode Object Storage, configure storage connections, clip the event then export.

Archive Modes: Understanding Current Setup

Before migrating, identify which archive mode the MSL4 stream is currently using:

Mode 1: Basic Archive – Event Purge Mode

• Purpose: Retain and export specific events only.
• Behavior:
  • Stream content is recorded during live stream.
  • Users select and retain specific events (by configuring event names) to object storage.
  • Other content is automatically purged after the retention period expires.
• Migration Impact: Users must continue the practice of actively defining events before retention expires. MSL5 does not automatically archive content.

Mode 2: Unlimited Archive Mode

• Purpose: Retain entire stream for extended access.
• Behavior:
  • Full live stream is recorded continuously.
  • Entire stream is archived to the Netstorage indefinitely.
• Migration Impact: In MSL5, export only the content or events that need to be retained. If full archive coverage is required, export the stream by clip event up to 12-hour blocks (typically 2 event blocks per day). Complete all required exports within the stream retention window (maximum 62 days).

Before Migration: Critical Prerequisites

Object Storage Setup (Required)

• MSL5 requires Akamai Linode Object Storage.
• Create a Linode account (if not already available)
• Provision Object Storage bucket in the user's preferred region
• Generate API credentials (Access Key + Secret Key)

📘

The Linode object storage endpoint format is, <bucket>.<region>.linodeobjects.com. For example,clips-export-bucket.us-ord-10.linodeobjects.com.

Store credentials securely (password manager or secure vault)

Identify Archive Details

• Current MSL4 stream ID
• Current archive retention period
• Active archive mode in use (Event Purge or Unlimited)
• Typical event duration and frequency
• Estimated storage size needed (calculate based on bitrate and duration)

After completing this step, users can follow migration planning guidance for other archive modes, such as Basic Archive - Event Purge and Unlimited Archive, in the official MSL5 Migration Guide - Final Phase .

Step-by-Step Migration Procedure

Migrate Streams from MSL4 to MSL5 first

1. Complete stream migration from MSL4 to MSL5.
2. Verify migrated streams appear as Active in MSL5 portal.

Default retention after migration

• For migrated MSL4 streams using Event Purge or Unlimited Archive modes, MSL5 applies a default 62-day retention after migration.
• Plan clipping and export operations within this 62-day window.

Choose your operating option after stream migration

After stream migration is complete, choose one of the following operating paths:

• Option A: UI workflow
  • Continue with UI Operations in this guide.
• Option B: API workflow
  • Go directly to API Operations and run the equivalent API calls.

Both options support the same migration objective. Choose based on your team's operational preference.

UI Operations

Use this section if you prefer the portal-based workflow.

Create Storage Connection in MSL5 Portal

1. Log into the MSL5 portal.

2. Navigate to Export Storage.

3. Click + Add connection.

4. Enter connection details:

   • Connection name: For example, Archive-Storage-Prod.
   • Contract: Select the target contract.
   • Group: Select the target group.
   • Linode object storage endpoint: Enter endpoint in format <bucket>.<region>.linodeobjects.com. For example, clips-export-bucket.us-ord-10.linodeobjects.com.
   • Folder (optional): For example, events/live-record.
   • Access key: Linode object storage access key ID.
   • Secret key: Linode object storage secret access key.

5. Click Save.

6. Verify the new storage connection appears in Export Storage list with active status.

Configure Event Clip in the UI

1. In MSL5 portal, open the migrated stream and click Clip event.

2. In Event details, verify:

   • Stream name
   • Event name

3. Configure clipping window:

   • Start time: Event start timestamp
   • End time: Event end timestamp

4. Clip the event.

Export to Storage Connection

1. In Event details, under Export, select storage target from Select storage connection.
2. Click Export.
3. Review Export History for completion or failure status.
4. Verify exported files in object storage bucket after export completes.

Event export can also be automated through API for users with integration requirements.

📘

Export Restrictions

• Export is asynchronous. After user clicks Export, monitor Export History for task completion or failure.
• The selected storage connection region must match the stream's primary region for the export.
• Only clipped events with valid start and end times can be exported.
• A maximum of 2 concurrent export sessions is allowed per account.
• Export throughput is 100 Mb/s per export session.
• If an active export already exists for the same event and storage connection, a new export cannot be started until the active export finishes or is canceled.
• Users must export within the archive retention window (default 62 days after migration for Event Purge and Unlimited Archive streams).

API Operations

This section is for users who prefer API-based execution, either for one-off calls or integration workflows.

API Authentication and Base URL

• Base URL: https\://{hostname}
• Authentication: Bearer JWT in Authorization header

Example header:

Authorization: Bearer <jwt_token>
Content-Type: application/json

Recommended API Call Sequence

1. Create or validate Linode object storage connection.
2. Create event clip (maximum 12-hour time range per event).
3. Create export task for that event.
4. Poll export task status until completion.
5. Cancel export task only if needed.

Key API Operations

Example 1: Create Storage Connection (Linode)

curl -X POST "https://{hostname}/api/v1/s3_storage_connections" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Archive-Storage-Prod",
    "endpoint": "https://clips-export-bucket.us-ord-10.linodeobjects.com",
    "access_key_id": "<linode_access_key>",
    "secret_access_key": "<linode_secret_key>",
    "contract_id": "<contract_id>",
    "group_id": "<group_id>",
    "folder": "events/live-record",
    "config": {}
  }'

Required fields from schema:

• display_name, endpoint, access_key_id, secret_access_key, contract_id, group_id, config.

Example 2: Create Event Clip (12-hour max)

curl -X POST "https://{hostname}/api/v1/streams/{stream_id}/events" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "archive-block-2026-06-18-00",
    "start_time": "2026-06-18T00:00:00Z",
    "end_time": "2026-06-18T12:00:00Z"
  }'

📘

API enforces end_time within 12 hours of start_time.

For full-day retention, create 2 event blocks per day, for example 00:00-12:00 and 12:00-24:00.

Example 3: Create Export Task

curl -X POST "https://{hostname}/api/v1/streams/{stream_id}/events/{event_name}/exports" \
  -H "Authorization: Bearer <jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "s3_storage_connection_id": "<storage_connection_id>"
  }'

Response is asynchronous (202 Accepted). Save export_id from response.

Example 4: Poll Export Status

curl -X GET "https://{hostname}/api/v1/streams/{stream_id}/events/{event_name}/exports/{export_id}" \
  -H "Authorization: Bearer <jwt_token>"

Track these response fields:

• status
• exported_bytes
• error_message (if failed)

Example 5: Cancel an active export

curl -X POST "https://{hostname}/api/v1/streams/{stream_id}/events/{event_name}/exports/{export_id}/cancel" \
  -H "Authorization: Bearer <jwt_token>"

API usage notes

• Start with selective export: export only events required for business, compliance, or replay.
• Complete required exports before the 62-day retention limit.
• Use list_event_exports and get_event_export to detect and retry failed exports.
• Do not submit duplicate exports for the same event and storage connection while one export is active.