Skip to content

Commit a1ca8a6

Browse files
shiongzuoandrewconnell
shiongzuo
and
andrewconnell
authored
Create migration-job-progress-api-reference.md (SharePoint#10303)
* Create migration-job-progress-api-reference.md * Update migration-job-progress-api-reference.md * Update migration-job-progress-api-reference.md Revised broken links * Update migration-job-progress-api-reference.md Replace with relative links * fix markdown issues, grammar, typos ## markdown in accordance with msdocs guidelines, applied the following changes: - always have empty lines between headings, paragraphs, and fenced code blocks - fenced code language fixes: - no such language **rest**... changed to `http` or `json` where applicable - used inline formatting where applicable --------- Co-authored-by: Andrew Connell <[email protected]>
1 parent ce29917 commit a1ca8a6

File tree

1 file changed

+171
-0
lines changed

1 file changed

+171
-0
lines changed

‎docs/apis/migration-job-progress-api-reference.md

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: "SharePoint Migration Job Progress API"
3+
description: "This article explains how to retrieve migration job status with GetMigrationJobProgress API."
4+
ms.date: 06/15/2025
5+
ms.author: jihongzuo
6+
author: shiongzuo
7+
manager: dapodean
8+
audience: ISV
9+
ms.subservice: migration-tool
10+
ms.topic: article
11+
ms.localizationpriority: high
12+
ms.collection:
13+
- SPMigration
14+
- m365-collaboration
15+
---
16+
# SharePoint GetMigrationJobProgress API
17+
18+
After submitting a migration job—whether an import job or an Asynchronous Metadata Read (AMR) job—you can use the GetMigrationJobProgress API to track its progress. The API is available via both SDK and REST interfaces.
19+
20+
It returns a sequence of job status events, including: JobQueued, JobStart, JobProgress, JobError, and JobEnd.
21+
22+
## Permissions
23+
24+
Use application-based authentication when submitting a migration job. Ensure the application is granted the Sites.Read.All permission or higher.
25+
26+
## GetMigrationJobProgress Method (SDK)
27+
28+
### Syntax
29+
30+
```csharp
31+
public ClientResult Site.GetMigrationJobProgress(
32+
Guid jobId,
33+
String nextToken
34+
)
35+
```
36+
37+
### Method Parameters
38+
39+
| Name | Type | Required | Description |
40+
| :--------- | :------- | :------- | :----------------------------------------------------- |
41+
| jobId | Guid | Yes | Unique identifier of the migration job |
42+
| nextToken | String | Yes | Token for paging position. Use "0" for initial request |
43+
44+
For a completed job, requests using nextToken are idempotent—repeating the same request will consistently return the same result.
45+
46+
### Return Values
47+
48+
| Name | Type | Description |
49+
| :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ |
50+
| Logs | IList | Returns a collection of job status events when new progress is available, or an empty collection if there are no updates. |
51+
| NextToken | String | Returns an updated string value when new progress is available, or the same value as the nextToken parameter if there are no updates. |
52+
53+
### Method Usage Example
54+
55+
```csharp
56+
ClientResult result = context.Site.GetMigrationJobProgress(jobId, nextToken ?? "0");
57+
context.ExecuteQuery();
58+
IList logs = result.Value.Logs;
59+
string newNextToken = result.Value.NextToken;
60+
```
61+
62+
## GetMigrationJobProgress REST API
63+
64+
### HTTP Request
65+
66+
```http
67+
GET https://{site_url}/_api/site/GetMigrationJobProgress(jobId='{jobId}',nextToken=0)
68+
```
69+
70+
### URI Parameters
71+
72+
| Name | Type | Required | Description |
73+
| :--------- | :------- | :------- | :----------------------------------------------------- |
74+
| jobId | Guid | Yes | Unique identifier of the migration job |
75+
| nextToken | String | Yes | Token for paging position. Use "0" for initial request |
76+
77+
### Request Headers
78+
79+
| Header | Required |
80+
| :------------------------------------- | :------- |
81+
| Authorization: Bearer {token} | Yes |
82+
| Accept: application/json;odata=verbose | Yes |
83+
84+
### Response
85+
86+
A JSON object when the HTTP status code is 200.
87+
88+
An empty JSON object when the HTTP status code is other than 200.
89+
90+
### Error Handling
91+
92+
| Status Code | Meaning | Action |
93+
| :---------- | :------------- | :---------------------------------------------------------------------- |
94+
| 403 | Unauthorized | Ensure the app/user has at least Sites.Read.All permissions. |
95+
| 429 | Too Many Requests | Parse Retry-After header and retry after the specified delay. |
96+
| 500 | Internal Server Error | Parse error responses to identify internal errors. Do Not Retry. |
97+
| 503 | Service Unavailable | Parse Retry-After header and retry after the specified delay. |
98+
99+
| Internal Error Code | Meaning |
100+
| :------------------ | :---------------------------------------------- |
101+
| -2147213145 | Job not found |
102+
| -2147213146 | Job status expired (valid for less than 5 days) |
103+
104+
### API Usage Example
105+
106+
#### Request Sample
107+
108+
```http
109+
GET https://contoso.sharepoint.com/_api/site/GetMigrationJobProgress(jobId=' 3e280efa-78a3-4ba1-bac6-e447aa538ca5', nextToken=0)
110+
```
111+
112+
#### Successful Response Sample
113+
114+
Status code: 200
115+
Response body:
116+
117+
```json
118+
{
119+
"d": {
120+
"GetMigrationJobProgress": {
121+
"Logs": {
122+
"__metadata": {
123+
"type": "Collection(Edm.String)"
124+
},
125+
"results": [
126+
"{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"SiteId\":\"48f1898f-77d9-4a1b-bddc-1f49bb6dc134\",\"DbId\":\"de6b85cd-726e-4b13-ae04-629798fddbf3\",\"TotalRetryCount\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:18:48.132\",\"CorrelationId\":\"91884a0c-5ee8-4e1f-a23f-e4f7ec170182\",\"Event\":\"JobQueued\"}",
127+
"{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"SiteId\":\"48f1898f-77d9-4a1b-bddc-1f49bb6dc134\",\"WebId\":\"7206fc09-e4af-48b3-8730-ed7321396d7a\",\"DbId\":\"de6b85cd-726e-4b13-ae04-629798fddbf3\",\"FarmId\":\"f77d7b6c-ef43-4609-8fce-0e93142ce8a0\",\"ServerId\":\"44af885c-393b-4236-9417-bae7a9edc44e\",\"SubscriptionId\":\"82abb045-250e-4186-ba83-b9295930f272\",\"TotalRetryCount\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:51.129\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobStart\"}",
128+
"{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"TotalRetryCount\":\"0\",\"ObjectType\":\"ListItem\",\"Url\":\"\",\"Id\":\"cb471d5f-593f-4a63-b59e-8eae3e35b08a\",\"SourceListItemIntId\":\"3\",\"TargetListItemIntId\":\"3\",\"ErrorCode\":\"-2147286782\",\"ErrorType\":\"Microsoft.SharePoint.SPException\",\"Message\":\"Attempted to use an object that has ceased to exist. (Exception from HRESULT: 0x80030102 (STG_E_REVERTED)) \",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:55.490\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobError\"}",
129+
"{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"TotalRetryCount\":\"0\",\"FilesCreated\":\"0\",\"BytesProcessed\":\"0\",\"ObjectsProcessed\":\"4\",\"TotalExpectedSPObjects\":\"15\",\"TotalErrors\":\"3\",\"TotalWarnings\":\"0\",\"WaitTimeOnSqlThrottlingMilliseconds\":\"0\",\"TotalDurationInMs\":\"0\",\"CpuDurationInMs\":\"0\",\"SqlDurationInMs\":\"0\",\"SqlQueryCount\":\"0\",\"IsShallowCopy\":\"False\",\"CreatedOrUpdatedFileStatsBySize\":\"{}\",\"ObjectsStatsByType\":\"{\\\"SPUser\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":124,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPFolder\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":153,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPDocumentLibrary\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":404,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPFile\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":0,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPListItem\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":1880,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0}}\",\"TotalExpectedBytes\":\"0\",\"FilesCreatedIrrespectiveOfVersions\":\"0\",\"BytesProcessedOnlyCurrentVersion\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:57.380\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobEnd\"}"
130+
]
131+
},
132+
"NextToken": "1764",
133+
"__metadata": {
134+
"type": "SP.MigrationJobProgress"
135+
}
136+
}
137+
}
138+
}
139+
```
140+
141+
#### Error Response Sample
142+
143+
Status code: 500
144+
Response body:
145+
146+
```json
147+
{
148+
"error": {
149+
"code": "-2147213145, Microsoft.SharePoint.SPException",
150+
"innererror": {
151+
"message": "Job not found",
152+
"stacktrace": "STACK_TRACE"
153+
},
154+
"message": {
155+
"lang": "en-US",
156+
"value": "Job not found"
157+
}
158+
}
159+
}
160+
```
161+
162+
## Best Practice
163+
164+
Begin with `nextToken=0`, store the returned token, and poll at certain intervals. This method is well-suited for long-running jobs and helps ensure no updates are missed.
165+
166+
Since migration jobs typically take several minutes or more, polling every minute is advised, while adhering to the [guideline](https://aka.ms/spo429) to avoid throttling.
167+
168+
## See Also
169+
170+
- [SharePoint Migration API](migration-api-overview.md)
171+
- [Migration Events](migration-events.md)

0 commit comments

Comments
 (0)