---
title: "Batch clone v2 accounts to v3 grants"
method: POST
path: "/v3/migration-tools/snapshot-batch-clone"
tags: ["App migration"]
---

# Batch clone v2 accounts to v3 grants

`POST /v3/migration-tools/snapshot-batch-clone`

Starts a batch migration job to clone v2 connected accounts to v3 grants.

Before you use this endpoint, your v2 Nylas applications need to be linked to their corresponding v3
applications and you need to have a working equivalent 
[authentication connector](/docs/reference/api/connectors-integrations/) for each provider
you use. If you need help with this process, [learn how to get support](/docs/support/).

When you make a batch clone request, Nylas starts two background jobs:

  - A snapshot job that prepares non-sensitive v2 account data for migration.
  - A batch clone job that migrates the v2 account data to v3 grants.

Nylas handles all data and logic for these jobs and runs them in the background to they don't block
API responses.

You can filter for certain types of accounts by specifying properties in the body of your request.
Use these options when you want to try migrating certain types of accounts in smaller batches,
or to retry failed migrations. If you don't specify any filters, Nylas uses the default values.

During migration, Nylas maps the v2 provider to its v3 equivalent using the connected account's
v2 authorization type and provider. All sensitive data (such as tokens and passwords) is encrypted
and securely transfered only within the Nylas infrastructure. No secrets exit the internal Nylas
network.

This endpoint is rate limited to 20 requests per second, per Nylas application ID.

### Create placeholder grants

Nylas can migrate existing Microsoft Graph, Office 365, and EWS accounts that use token
authentication. It can't fully migrate
[some types of Microsoft accounts](/docs/v2/upgrade-to-v3/upgrade/migrating-microsoft-accounts/#microsoft-account-import-compatibility-in-v3)
because of provider limitations and scope changes in v3.

By default, Nylas creates an invalid v3 Grant with fake credentials for accounts that it can't
automatically migrate. These grants act as "placeholders" that the user can manually authenticate
to later. You can turn this feature off for Microsoft accounts only by setting the `clone_exchange`
query parameter to `false`, or for all providers by setting `allow_invalid_grant_creation` to
`false`.

## Query parameters

- `allow_invalid_grant_creation` boolean
- `clone_exchange` boolean

## Request body

- object
  - `limit` integer — Number of accounts to migrate. Nylas orders the migration records created by the snapshot job, by `imported_at` timestamp from oldest to newest.
  - `offset` integer — Number of accounts to skip. Nylas orders the migration records created by the snapshot job, by `imported_at` timestamp from oldest to newest.
  - `providers` string[] — Use this setting to limit the migration job to a specific provider or providers, so you can migrate one type at a time.
  - `mode` 'all' | 'only_new' | 'only_failed' — Use this setting to limit the migration job to accounts that have specific statuses, or when retrying failed migrations. - 'all': No filtering, migrate all accounts that meet the request criteria. - 'only_new': Migrate only accounts that haven't attempted migration. - 'only_failed': Migrate only accounts that attempted migration previously and were marked as failed.

## Response `200`

Immediately returns a list of the two jobs for the migration run:, snapshot and batch clone. Those jobs continue to synchronously run in the background.

- object
  - `request_id` string — The request ID.
  - `data` object
    - `clone_job` MigrationJob
      - `job_id` string, required — An identifier for the migration job.
      - `type` 'snapshot' | 'migration', required — The type of job.
      - `public_application_id` string, required — The ID of v3 application this job is running for.
      - `status` 'pending' | 'running' | 'completed' | 'failed' | 'partial', required — The state of the job. - **Pending**: The job has been created, but not started. Batch clone runs only after the linked snapshot job is completed. - **Running**: The job is currently running. - **Completed**: The job has successfully finished all migrations. - **Failed**: _All_ migrations failed. - **Partial**: The job successfully migrated _some_ accounts, but some could not be migrated or were created as "placeholder" grants.
      - `count_all` integer, required — A total number of accounts to be migrated. The total is a sum of the successful and failed migrations.
      - `count_success` integer, required — The number of accounts that were successfully migrated.
      - `count_failed` integer, required — The number of accounts that were unable to migrate.
      - `count_warning` integer, required — The number of accounts that were migrated as invalid grants ("placeholder" grant ready for re-authentication).
      - `created_at` integer, required — The time when the job was created, in seconds using the Unix timestamp format.
      - `updated_at` integer, required — The time the job was updated, in seconds using the Unix timestamp format.
      - `linked_job_id` string — The bulk migration tool creates two separate jobs that run one after the other. This ID links them together.
    - `snapshot_job` MigrationJob
      - `job_id` string, required — An identifier for the migration job.
      - `type` 'snapshot' | 'migration', required — The type of job.
      - `public_application_id` string, required — The ID of v3 application this job is running for.
      - `status` 'pending' | 'running' | 'completed' | 'failed' | 'partial', required — The state of the job. - **Pending**: The job has been created, but not started. Batch clone runs only after the linked snapshot job is completed. - **Running**: The job is currently running. - **Completed**: The job has successfully finished all migrations. - **Failed**: _All_ migrations failed. - **Partial**: The job successfully migrated _some_ accounts, but some could not be migrated or were created as "placeholder" grants.
      - `count_all` integer, required — A total number of accounts to be migrated. The total is a sum of the successful and failed migrations.
      - `count_success` integer, required — The number of accounts that were successfully migrated.
      - `count_failed` integer, required — The number of accounts that were unable to migrate.
      - `count_warning` integer, required — The number of accounts that were migrated as invalid grants ("placeholder" grant ready for re-authentication).
      - `created_at` integer, required — The time when the job was created, in seconds using the Unix timestamp format.
      - `updated_at` integer, required — The time the job was updated, in seconds using the Unix timestamp format.
      - `linked_job_id` string — The bulk migration tool creates two separate jobs that run one after the other. This ID links them together.

## Other responses

- `400` — Bad Request
- `401` — Not Authenticated

---

[API](https://skmtc.dev/nylas/apis/nylas-api.md) · [All operations](https://skmtc.dev/nylas/apis/nylas-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nylas/nylas-api/revisions/51c2c1b4ecff/schema)