Group relations export API

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

Use this API to migrate a group structure. Each top-level relation (for example, milestones, boards, and labels) is stored as a separate file.

This API is primarily used during group migration by direct transfer. To use this API, 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:

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"
}

Export status

View the status of the 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
  }
]

Export download

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