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.

By default, this endpoint is limited to 6 requests per minute for each user and group. Requests over the limit return 429 Too Many Requests. On GitLab Self-Managed and GitLab Dedicated, administrators can change this limit.

POST /groups/:id/export_relations
AttributeTypeRequiredDescription
idInteger or stringYesID of the group.
batchedBooleanNoWhether to export in batches.
shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/export_relations"
json
{
  "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 group top-level relation to view.
shell
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
json
[
  {
    "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.

By default, this endpoint is limited to 100 requests per minute for each user and group. Requests over the limit return 429 Too Many Requests. On GitLab Self-Managed and GitLab Dedicated, administrators can change this limit.

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