> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitor, cancel, and roll back platform migrations from Settings → Migrations

> Use the Settings → Migrations page to watch platform import jobs (Twilio, Telnyx, Klaviyo, MessageBird, Front), cancel a running migration, roll back a finished one, and know when a job is stuck — outside the onboarding wizard.

# Monitor, cancel, and roll back platform migrations

The import wizard carries you from connect to run, but the wizard's progress view is the only screen that exists while onboarding is open. Once you close it, the durable operations surface for migration jobs is **Settings → Migrations** in the dashboard. This page lists every platform-migration job your organization has run and is where you cancel a migration that is going wrong or roll back one that already landed. The full wizard walkthrough lives in [run a platform migration end-to-end](/guides/platform-migration-jobs); this guide is the operations half of the lifecycle.

Open it from the dashboard sidebar: **Settings → Migrations**.

## 1. What the page lists

Each row is one persisted migration job for your organization, showing:

* **Source** — the platform the job pulled from: Twilio, Telnyx, Klaviyo, MessageBird, or Front.
* **Status** — the job's current state in the lifecycle (`pending`, `running`, `succeeded`, `failed`, `cancelled`).
* **Started** — when the job began, in your timezone. After a rollback, the row also shows a "rolled back" marker so you can tell a reverted migration apart from one that still stands.

The list refreshes on demand via the **Refresh** button, and each row exposes up to two actions — **Cancel** and **Roll back** — gated by the job's state and your role.

## 2. Status and what each state allows

Migration jobs follow the same state machine the [troubleshooting table](/troubleshooting/import-jobs) documents:

| Status                             | Cancel allowed                     | Roll back allowed     |
| ---------------------------------- | ---------------------------------- | --------------------- |
| `pending`, `running`               | Yes — stops at the next checkpoint | No — cancel first     |
| `succeeded`, `failed`, `cancelled` | No — the job is already terminal   | Yes — run it promptly |

Terminal means the job never moves again. Three consequences fall out of that:

* **Cancel is only offered on `pending` and `running` rows.** Asking to cancel a terminal job comes back as a conflict — read it as "already finished," not as a failure.
* **Rolling back a job that is still in flight is refused** — cancel it, wait for it to settle into a terminal state, then roll back.
* **Run rollback promptly.** The rollback window for import jobs is 24 hours after the job finished; past that, remove leftover rows with a targeted bulk delete instead of a job-level rollback. A job that was already rolled back is rejected as already done — second attempts are safe but change nothing, and the row's rolled-back marker tells you the first one landed.

## 3. Cancel a running migration

Useful when the job is importing the wrong scope, or the upstream account turned out to be stale.

1. On the job's row, click **Cancel**.
2. Read the confirm dialog — it states the outcome — and confirm with **Cancel migration**. Use **Keep running** to back out.

Cancel is best-effort: the worker flips the job to `cancelled` the next time it reaches a safe checkpoint between batches, so the stop is clean rather than mid-batch. What the semantics mean in practice:

* **Already-imported data stays.** Cancel stops future work; it does not undo past work. Your workspace may be partially migrated.
* **The job ends in `cancelled`**, a terminal state — you cannot resume it. Re-run the wizard to restart.
* **Rollback remains available after the cancel** lands, so the full reversal is cancel → wait for the terminal state → roll back.

If cancel refuses because the job finished in the meantime, the confirm error tells you the job's actual status — refresh and the row shows its final state.

## 4. Roll back a finished migration

Rollback is restricted to the **owner** or **admin** role; other roles see the job list but never get the button.

1. On a terminal job's row, click **Roll back**.
2. Read the confirm dialog — rollback **permanently deletes every contact this job created** — and confirm.

Scope worth knowing before you confirm:

* **Contacts the job created are deleted.** The success toast reports how many rows were removed.
* **Pre-existing contacts the job merely updated are untouched** — rollback never destroys data that existed before the migration.
* **Imported non-contact configuration** (imported routing, channel settings) is out of rollback's scope and stays.
* **A job rolls back once.** After a successful rollback the row carries the rolled-back marker and the count, and a second attempt is rejected — there is nothing left to remove.

If rollback refuses with "still running," the job has not finished settling — wait for the status to go terminal. If it refuses with "already rolled back," someone on your team got there first.

## 5. Platform migrations vs contact CSV imports

Both show up under "import jobs," but they are different lifecycles:

* **Platform migration (this page)** — Orbit pulls contacts *and* platform configuration over an authenticated connection to Twilio, Telnyx, Klaviyo, MessageBird, or Front. Jobs appear on **Settings → Migrations**. Run one from the provider-migration hub on **Settings → Integrations**, or from onboarding.
* **Contact CSV import** — you upload a shaped file of rows over the API or from **Audience → Imports**. Jobs appear on the contacts import history, not here. See [import and reconcile contacts](/guides/import-contacts).

The two paths share the underlying state machine and the same cancel/rollback vocabulary — one model, two entry points — which is documented on the [import and migration lifecycle](/concepts/imports-migration-model) concept page. The per-error decisions (`IMPORT_NOT_CANCELLABLE`, `IMPORT_STILL_RUNNING`, `ALREADY_ROLLED_BACK`, queue unavailability) live in [troubleshooting: contact imports](/troubleshooting/import-jobs).

## 6. When to escalate

Most Migrations-page problems resolve locally — refresh the list, read the job's live status, match your action to the state table above. Escalate when:

* a job sits in `pending` for more than a few minutes (the worker should pick it up almost immediately),
* a `running` job stops advancing and cancel does not move it to `cancelled`,
* cancel or rollback keeps returning conflicts after a refresh, or
* a rollback completed but you suspect imported contacts remain.

When you open a ticket, include:

1. **Your organization / tenant id** — visible in the dashboard URL and on Settings → Organization.
2. **The job id** — the `imp_…` identifier for the migration (shown on the API response for the job list; quote it when you contact support).
3. **The response's `meta.request_id`** for any failing API call — support can replay the exact state of the request from that id.

With those three, support replay is one lookup instead of a reconstruction.

## See also

* [Run a platform migration end-to-end](/guides/platform-migration-jobs) — the wizard side: connect, dry-run preview, live progress, and the equivalent API calls
* [Migrate from Twilio](/guides/migration-from-twilio) — the concept mapping (numbers, messaging services, TwiML, webhooks) for the most common source
* [Import and migration lifecycle](/concepts/imports-migration-model) — the state machine and entity model underneath both import paths
* [Troubleshooting: contact imports](/troubleshooting/import-jobs) — per-error-code fixes for cancel, rollback, and queue failures
* [Import and reconcile contacts](/guides/import-contacts) — the CSV import path for sources without a connector
* [Opt-out lists](/guides/opt-out-lists) — consent enforcement that applies to migrated contacts exactly as it does to any other audience