Project relations export API

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

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

The project relations export API is primarily used in group migration can’t be used with the project import and export API.

Schedule new export

Start a new project relations export:

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

Export status

View the status of the relations export:

GET /projects/:id/export_relations/status
AttributeTypeRequiredDescription
idinteger/stringyesID of the project.
relationstringnoName of the project top-level relation to view.
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/1/export_relations/status"

The status can be one of the following:

  • 0 - started
  • 1 - 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
  }
]

Export download

Download the finished relations export:

GET /projects/:id/export_relations/download
AttributeTypeRequiredDescription
idinteger/stringyesID of the project.
relationstringyesName of the project top-level relation to download.
batchedbooleannoWhether the export is batched.
batch_numberintegernoNumber of export batch to download.
curl --header "PRIVATE-TOKEN: <your_access_token>" --remote-header-name \
     --remote-name "https://gitlab.example.com/api/v4/projects/1/export_relations/download?relation=labels"
ls labels.ndjson.gz
labels.ndjson.gz