Group relations export API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

The group relations export API partially exports a group’s structure as separate files for each top-level relation (for example, milestones, boards, and labels).

The group relations export API is primarily used in group migration by direct transfer and your GitLab instance must meet certain prerequisites.

This API can’t be used with the group import and export API.

Schedule new export

Start a new group relations export:

Copy to clipboard
POST /groups/:id/export_relations
AttributeTypeRequiredDescription
idinteger/stringyesID of the group.
batchedbooleannoWhether to export in batches.
Copy to clipboard
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/export_relations"
Copy to clipboard
{
  "message": "202 Accepted"
}

Export status

View the status of the relations export:

Copy to clipboard
GET /groups/:id/export_relations/status
AttributeTypeRequiredDescription
idinteger/stringyesID of the group.
relationstringnoName of the project top-level relation to view.
Copy to clipboard
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
     "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
Copy to clipboard
[
  {
    "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
  }
]

Export download

Download the finished relations export:

Copy to clipboard
GET /groups/:id/export_relations/download
AttributeTypeRequiredDescription
idinteger/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.
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \
     --remote-name "https://gitlab.example.com/api/v4/groups/1/export_relations/download?relation=labels"
Copy to clipboard
ls labels.ndjson.gz
labels.ndjson.gz