Project relations export API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, 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:

Copy to clipboard 
POST /projects/:id/export_relations
Attribute Type Required Description
id integer/string yes ID of the project.
batched boolean no Whether to export in batches.
Copy to clipboard 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/export_relations"
Copy to clipboard 
{
  "message": "202 Accepted"
}

Export status

View the status of the relations export:

Copy to clipboard 
GET /projects/:id/export_relations/status
Attribute Type Required Description
id integer/string yes ID of the project.
relation string no Name 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/projects/1/export_relations/status"

The status can be one of the following:

  • 0 - started
  • 1 - finished
  • -1 - failed
Copy to clipboard 
[
  {
    "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:

Copy to clipboard 
GET /projects/:id/export_relations/download
Attribute Type Required Description
id integer/string yes ID of the project.
relation string yes Name of the project top-level relation to download.
batched boolean no Whether the export is batched.
batch_number integer no Number 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/projects/1/export_relations/download?relation=labels"
Copy to clipboard 
ls labels.ndjson.gz
labels.ndjson.gz