Use this guide as a reusable framework for planning and carrying out migrations across LangSmith deployment models.

Supported migration paths

• SaaS ⇔ SaaS

• SaaS ⇔ BYOC

• SaaS ⇔ self-hosted on AWS, Azure, or Google Cloud

• Self-hosted ⇔ self-hosted, including migrations between AWS, Azure, and Google Cloud

• Self-hosted ⇔ BYOC

The guide covers organization configuration, authentication, users, workspaces, projects, application resources, integrations, and historical data. The overall workflow is consistent across these paths, but prerequisites, networking, identity configuration, infrastructure ownership, and cutover steps will vary by source and destination.

It assumes you have administrator access to both environments and can coordinate a change window with the teams whose applications send traces.

Migration Checklist Steps

1. Define the migration scope and target outcome.

2. Identify owners and stakeholders.

3. Review compatibility and prerequisites.

4. Prepare the destination environment.

5. Configure access and migration tooling.

6. Run a pilot migration.

7. Migrate users and application resources.

8. Restore credentials and integrations.

9. Plan the live traffic transition.

10. Migrate required historical data.

11. Validate the destination environment.

12. Complete cutover and close the migration.

Recommended Approach: Two Phases

Running the migration in two phases lets you validate the destination environment against live traffic before committing to cutover. This reduces risk and creates a clear decision point between setup and final migration.

Migration Tool Capabilities, Limitations and Actions

Most resource migration is handled by the open-source LangSmith Data Migration Tool. Understanding its boundaries up front is the single biggest factor in a smooth migration.

Prerequisites

1. Define the migration scope and target outcome

Document the source and destination deployment models, cloud providers, regions, and versions. Define the reason for the migration, what is included or excluded, the expected timeline, and the criteria that will determine whether the migration is successful.

2. Identify owners and stakeholders

Identify the migration lead, technical owners, application teams, and relevant security, identity, networking, and platform contacts. Agree who can make decisions, approve each stage, validate the result, and manage communications or escalations.

3. Review compatibility and prerequisites

Confirm that the source, destination, application SDKs, and migration tooling are compatible. Review differences in versions, features, licences, capacity, permissions, retention, and configuration. Record any upgrades, platform changes, limitations, or manual work required before migration.

4. Prepare the destination environment

Provision the destination and configure the required organizations, workspaces, authentication, networking, security, storage, monitoring, and administrative access. Confirm that it has enough capacity for both live usage and migration activity, and record any required source-to-destination mappings.

Configure Migration Tool

1. Configure access and migration tooling

Select the supported migration-tool version or approved migration method. Create the required source and destination credentials, confirm connectivity, and configure workspace mappings and migration filters.

Install UV and migration tool package

uv tool install "langsmith-data-migration-tool @ git+https://github.com/langchain-ai/langsmith-data-migration-tool.git"

Configure source and destination credentials

export LANGSMITH_OLD_API_KEY="<source org admin PAT>"
export LANGSMITH_OLD_BASE_URL="<source base URL>"
export LANGSMITH_NEW_API_KEY="<destination org admin PAT>"
export LANGSMITH_NEW_BASE_URL="<destination base URL>"

List projects and create workspace mappings

langsmith-migrator list-projects --source
langsmith-migrator users --map-workspaces

The workspace mapping is stored in ~/.langsmith-migrator/config.json.

2. Run a pilot migration

Use a representative organization, workspace, project, or data range to test the migration process. Review successful, failed, skipped, and blocked items. Validate the migrated content, record required manual actions, and update the wider migration plan before proceeding.

langsmith-migrator test

3. Migration Process

Option A: Migrate all resources using one command

The migration tool can migrate all supported LangSmith resources in a single operation, except those listed under Migration Tool Limitations. You can also migrate resource types individually. To migrate all supported resources, run:

langsmith-migrator migrate-all --map-projects

Option B: Migrate individual resources using multiple commands

Migrate resources in dependency order. The first three activities mapping workspaces, mapping projects, and migrating users, roles, and memberships are completed in one guided workflow.

1. Map workspaces and projects, then migrate users

langsmith-migrator users --map-workspaces

In the interactive interface:

1. Press a to automatically match workspaces by name.

2. Press c to create any remaining unmapped source workspaces in the destination.

3. For each mapped workspace pair, press p to open project mapping and match its projects.

4. Press Ctrl+S to save the mappings and continue with the user, role, and membership migration.

The tool saves workspace and per-workspace project mappings to ~/.langsmith-migrator/config.json. Subsequent commands offer to reuse this configuration.

2. Migrate datasets and experiments

langsmith-migrator datasets --all --include-experiments

3. Migrate prompts

langsmith-migrator prompts --all

4. Migrate annotation queues

langsmith-migrator --non-interactive queues

5. Migrate automation rules

langsmith-migrator rules --all --map-projects

By default, migrated rules are disabled. Add --create-enabled only if they should be active immediately in the destination.

6. Migrate dashboards and charts

langsmith-migrator charts --map-projects

7. Migrate model pricing

langsmith-migrator --non-interactive model-pricing

8. Migrate Context Hub repositories

langsmith-migrator contexts --all

9. Migrate Engine

langsmith-migrator issues --all --map-projects

10. Fleet (agents, skills, MCP servers, secrets, auth providers, triggers, webhooks, usage limits, sandbox policies)

langsmith-migrator fleet

After each command, review migrated, failed, skipped, and blocked items. Resolve blockers, retry incomplete work where appropriate, and compare source and destination counts. To resume an interrupted migration, run:

langsmith-migrator resume

4. Validation and Follow On Actions

1. Restore credentials and integrations

Create replacement API keys, access tokens, secrets, and authentication settings that cannot be transferred. Reconnect external integrations, update application endpoints and credentials, restore ownership or sharing where required, and test each integration before production use.

2. Plan the live traffic transition

Choose an appropriate transition method, such as direct cutover, staged cutover, a temporary pause, or dual-write. Define the cutover window, application changes, validation period, communications, rollback steps, and the conditions for continuing or reverting the migration. If dual-write is used, preserve identifiers where required to prevent duplicate traces.

3. Historical trace data

The resource migration tool does not migrate trace data. Decide early which outcome you need, because the options below solve different problems and have different operational costs.

Option A: Retain history outside LangSmith (available today)

Use Bulk Export to export historical traces from the source instance into your own object storage or data lake. This preserves the data for analysis, audit, and compliance.

Option B: Keep the source instance readable (available today)

Freeze writes to the source at cutover, but keep the instance available in read-only mode for an agreed period so teams can consult historical traces. Set a planned decommission date and define who retains access during the transition.

This avoids a large transfer entirely and is often sufficient when historical traces are consulted occasionally rather than queried routinely.

Option C: Migrate traces into SaaS (in development)

Native migration of historical traces into LangSmith SaaS is not available in the released tool. If destination-native history is a hard requirement, contact support@langchain.dev before planning cutover so scope, eligibility, and timing can be assessed for your environment. Use the same address for any trace migration questions, issues, or concerns.

Two constraints determine potential eligibility:

• Eligibility is based on the retention tier attached to each trace when it was originally ingested, not the project's retention setting today.

• Changing a project's retention setting is not retroactive. Switching a project to extended retention now does not make older traces eligible.

Audit which projects historically used extended retention and reconcile their eligible volume against the total trace volume. The eligible subset may be significantly smaller than the raw total.

Planning a large transfer

For volumes measured in tens of terabytes or more, transfer capacity usually becomes the dominant constraint rather than the migration tooling.

1. Measure sustained throughput on the intended path and confirm the units.

2. Determine whether the bottleneck can be lifted during the transfer window.

3. Complete security, capacity, and operational approvals before committing to a date.

4. Agree the transfer schedule and name owners for monitoring, retries, and escalation.

5. If data at rest is encrypted, confirm which identity can read and decrypt it.

Validation

1. Validate the destination environment

Compare the source and destination, validate representative resources and data, and test user access, applications, workflows, and integrations. Confirm that monitoring and operational support are ready, resolve or accept migration exceptions, and obtain stakeholder approval.

2. Complete cutover and close the migration

Move live traffic to the destination and confirm that applications and users are operating normally. Stop source writes only after approval, monitor the destination during the agreed validation period, complete final reconciliation and sign-off, and retain or decommission the source according to the approved plan.