Group 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 group structure. You don’t usually need to use this API yourself.

In this context, a ​ is an exportable item such as an epic. 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 group

Schedules a relations export for a specified group.

POST /groups/:id/export_relations
AttributeTypeRequiredDescription
idInteger or stringYesID of the group.
batchedBooleanNoWhether to export in batches.
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/export_relations"
{
  "message": "202 Accepted"
}

Retrieve the status of an export

Retrieve the status of a relations export.

GET /groups/:id/export_relations/status
AttributeTypeRequiredDescription
idInteger or stringYesID of the group.
relationStringNoName of the project top-level relation to view.
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/export_relations/status"

The status can be one of the following:

  • 0: started
  • 1: finished
  • -1: failed
[
  {
    "relation": "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.

GET /groups/:id/export_relations/download
AttributeTypeRequiredDescription
idInteger or stringYesID of the group.
relationStringYesName of the group top-level relation to download.
batchedBooleanNoWhether the export is batched.
batch_numberIntegerNoNumber of export batch to download.
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --remote-header-name \
  --remote-name "https://gitlab.example.com/api/v4/groups/1/export_relations/download?relation=labels"
ls labels.ndjson.gz
labels.ndjson.gz