Project relations export API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
This API is used by the destination instance during group migration by direct transfer to migrate a project structure. You don’t usually need to use this API yourself.
In this context, a is an exportable item such as a merge request. When exported, the relation includes any items related to the relation such as a label.
If you want to use this API, your GitLab instance must meet certain prerequisites.
This API can’t be used with the group import and export API, which is for file-based migration.
Schedule a new export for a project
Schedules a relations export for a specified project.
By default, this endpoint is limited to 6 requests per minute for each user and project. Requests over the limit
return 429 Too Many Requests. On GitLab Self-Managed and GitLab Dedicated, administrators can
change this limit.
POST /projects/:id/export_relations| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID of the project. |
batched | boolean | No | Whether to export in batches. |
curl --request POST \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/1/export_relations"{
"message": "202 Accepted"
}Retrieve the status of an export
Retrieve the status of a relations export.
GET /projects/:id/export_relations/status| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID of the project. |
relation | string | No | Name of the project top-level relation to view. |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/projects/1/export_relations/status"The status can be one of the following:
0:started1:finished-1:failed
[
{
"relation": "project_badges",
"status": 1,
"error": null,
"updated_at": "2021-05-04T11:25:20.423Z",
"batched": true,
"batches_count": 1,
"batches": [
{
"status": 1,
"batch_number": 1,
"objects_count": 1,
"error": null,
"updated_at": "2021-05-04T11:25:20.423Z"
}
]
},
{
"relation": "boards",
"status": 1,
"error": null,
"updated_at": "2021-05-04T11:25:20.085Z",
"batched": false,
"batches_count": 0
}
]Download an export
Download the finished relations export.
By default, this endpoint is limited to 100 requests per minute for each user and project. Requests over the limit
return 429 Too Many Requests. On GitLab Self-Managed and GitLab Dedicated, administrators can
change this limit.
GET /projects/:id/export_relations/download| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | ID of the project. |
relation | string | Yes | Name of the project top-level relation to download. |
batched | boolean | No | Whether the export is batched. |
batch_number | integer | No | Number of export batch to download. |
curl --request GET \
--header "PRIVATE-TOKEN: <your_access_token>" \
--remote-header-name \
--remote-name \
--url "https://gitlab.example.com/api/v4/projects/1/export_relations/download?relation=labels"ls labels.ndjson.gz
labels.ndjson.gz