SharePoint Online migration: complete reference

Last updated August 4, 2026 · By Sean Regan

1. Migration scenarios

Microsoft's free SharePoint Migration Tool (SPMT) supports on-premises and file-share sources but does not support tenant-to-tenant migration^[1]. Cross-tenant scenarios require either Microsoft's preview Cross-Tenant SharePoint Migration service or a third-party / open-source tool that calls the Migration API directly.

2. The SharePoint Migration API

The Migration API is the only Microsoft-supported path that preserves full fidelity at production throughput. The flow is asynchronous^[3]:

1. The client builds a migration package: the source files plus two XML manifests (ExportSettings.xml andManifest.xml) describing items, versions, authors, timestamps, and permissions.
2. The package is uploaded to an Azure Blob Storage container the tenant provisions viaProvisionMigrationContainers.
3. The client callsCreateMigrationJob, which queues a server-side import job and returns a job ID.
4. SharePoint Online imports the package server-side, writing to the Azure Queue with progress and error events. The client polls the queue, not the API, which is what lets the Migration API sustain throughput where direct uploads would be throttled.

3. Fidelity: what is and is not preserved

4. Identity mapping

Source user identities (Windows SIDs, on-premises UPNs, or another tenant's GUIDs) cannot exist in the target tenant. They must be mapped to target principals at migration time^[2]. The Migration API consumes a UserAndGroupMapping.xml file with one row per source principal. Unmapped principals are written to the import asi:0#.f|membership|unknown and surface as broken Created By / Modified By fields in the target — they cannot be retroactively fixed without re-running the import.

Build the mapping file from the source by enumerating every distinct principal across all libraries (Created By, Modified By, role assignments on items with unique permissions), then resolve each to a target UPN via Microsoft Graph /users.

5. Throttling and rate limits

SharePoint Online enforces resource units per tenant per minute. Migration API jobs run server-side and do not consume the same quota as direct REST calls, which is why migrations that work for the first 50GB suddenly start failing the moment a script switches to direct upload^[4]. Practical rules:

• Always honor Retry-After response headers — Microsoft documents that ignoring them results in escalating throttles up to 24h blocks^[4].
• Use an app registration with certificate authentication, not delegated user credentials. User-context tokens are throttled aggressively.
• Run migrations off-hours in the target's timezone. The same job that throttles at 9am completes clean at 10pm.
• Cap concurrent migration jobs per site collection to ~4. Server-side import is already parallelized inside each job.

6. Tooling options

See the full comparisons: ShareGate, AvePoint, Quest, Metalogix, SPMT.

7. Post-migration verification

Treat verification as a separate engineering pass, not a smoke test. The minimum checklist:

1. Counts — source vs target item count per library; flag any delta > 0.
2. Checksums — SHA-256 of file content for a 1% random sample.
3. Timestamps — source vs target Created/Modified for the same sample.
4. Permissions — export a per-scope permissions report on the target and diff against the source. See the permissions inheritance reference for what to expect.
5. Version history depth — confirm version counts match per item.
6. Identity — query the target for any author resolving to System Account or unknown; these indicate UserAndGroupMapping gaps.

References

1. [1] Microsoft Learn — Introducing the SharePoint Migration Tool (SPMT)
2. [2] Microsoft Learn — User and group identity mapping for SharePoint migration
3. [3] Microsoft Learn — Migration API overview
4. [4] Microsoft Learn — Avoid getting throttled or blocked in SharePoint Online
5. [5] Microsoft Graph — driveItem resource type

Related

• SharePoint permissions inheritance: complete reference · SharePoint governance: complete reference