---
title: "Get migration jobs"
method: GET
path: "/v3/migration-tools/jobs"
tags: ["App migration"]
---

# Get migration jobs

`GET /v3/migration-tools/jobs`

Get information about the migration jobs for your application, including progress and status, for currently running and finished jobs.

Migration Jobs are a background task. After you start one Nylas returns a success response, and the jobs run in the background until they finish. These jobs do not block other API calls, but also do not send a notification when complete. This API allows you to get general information about a them, so you can see their status. 

There are two types of migration job: "snapshot" and "migration". A Snapshot job takes a snapshot of the application's v2 account data, and prepares it for migration. A Migration job actually turns the v2 account data into v3 grants.

Jobs have a status, which can be one of the following:
- A _pending_ job is queued and waiting to start.
- A _running_ job is currently in progress.
- A _partial_ job has finished, but was not able to migrate all accounts successfully.
- A _completed_ job has finished and successfully migrated _all_ accounts.
- A _failed_ job has finished but did not migrate any accounts.

You can optionally filter the list of jobs to return only jobs with a specific status or type.

You can also use the `sort_by_completion` argument to return the list of jobs with pending and running jobs first, followed by failed, completed, and partial jobs. Finished jobs are ordered by their completion timestamp (`CompletedAt`) from the most recent to the oldest.

If you don't include any query parameters to filter the results, Nylas returns all jobs.

The API is rate limited to 20 requests per second per Nylas application ID.

## Query parameters

- `status` string[]
- `type` string[]
- `sort_by_completion` boolean

## Response `200`

Returns a list of jobs.

- object
  - `request_id` string — The request ID.
  - `data` 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)