Job artifacts

Use this API to download, keep, and delete job artifacts.

Delete all job artifacts in a project

DELETE /api/v4/projects/{id}/artifacts

Deletes job artifacts from all jobs in a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project

Responses

Code	Description	Schema
`202`	Accepted	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—
`409`	Conflict	—

Retrieve job artifacts

GET /api/v4/projects/{id}/jobs/artifacts/{ref_name}/download

Retrieves the artifacts archive for the latest successful job on a specified branch or tag.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`ref_name` Path, required	String	Branch or tag name in the repository. `HEAD` or SHA references are not supported. For merge request pipelines, use `refs/merge-requests/:iid/head` instead of the branch name
`job` Query, required	String	Name of the job
`job_token` Query	String	CI/CD job token for multi-project pipelines. Premium and Ultimate only
`search_recent_successful_pipelines` Query	Boolean	If `true`, searches across recent successful pipelines instead of just the latest one. Introduced in GitLab 18.7 with a feature flag named `ci_search_recent_successful_pipelines`. Disabled by default Default: `false`
`download_mode` Query	String	Requested download transfer mode (`proxy` or `direct`). Only honored when allowed by the object storage configuration Allowed values: `proxy`, `direct`

Responses

Code	Description	Schema
`200`	OK	String (binary) (`application/octet-stream`)
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Download a specific file from artifacts archive from a ref

GET /api/v4/projects/{id}/jobs/artifacts/{ref_name}/raw/{artifact_path}

This feature was introduced in GitLab 11.5

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`ref_name` Path, required	String	Branch or tag name in the repository. `HEAD` or SHA references are not supported. For merge request pipelines, use `refs/merge-requests/:iid/head` instead of the branch name
`job` Query, required	String	Name of the job
`artifact_path` Path, required	String	Path to a file inside the artifacts archive
`job_token` Query	String	CI/CD job token for multi-project pipelines. Premium and Ultimate only
`search_recent_successful_pipelines` Query	Boolean	If `true`, searches across recent successful pipelines instead of just the latest one. Introduced in GitLab 18.7 with a feature flag named `ci_search_recent_successful_pipelines`. Disabled by default Default: `false`

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Download an artifact from a job

GET /api/v4/projects/{id}/jobs/{job_id}/artifacts

This feature was introduced in GitLab 8.5. The file_type attribute was added in GitLab 19.4.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`job_id` Path, required	Integer	ID of the job
`file_type` Query	String	Type of artifact to download. Set a specific report type to download that report file directly instead of the full artifacts archive. `performance` and `browser_performance` share a report group. If the job uploaded both, the requested type is returned, and if it uploaded only one, that artifact is returned whichever type was requested. Introduced in GitLab 19.4 Allowed values: `accessibility`, `api_fuzzing`, `archive`, `cobertura`, `jacoco`, `codequality`, `container_scanning`, `dast`, `dependency_scanning`, `dotenv`, `junit`, `license_scanning`, `lsif`, `metrics`, `performance`, `browser_performance`, `load_performance`, `sast`, `secret_detection`, `requirements`, `requirements_v2`, `cluster_image_scanning`, `cyclonedx`, `sarif` Default: `archive`
`job_token` Query	String	CI/CD job token for multi-project pipelines. Premium and Ultimate only
`download_mode` Query	String	Requested download transfer mode (`proxy` or `direct`). Only honored when allowed by the object storage configuration Allowed values: `proxy`, `direct`

Responses

Code	Description	Schema
`200`	OK	String (binary) (`application/octet-stream`)
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Delete job artifacts

DELETE /api/v4/projects/{id}/jobs/{job_id}/artifacts

Deletes job artifacts from a specified job in a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`job_id` Path, required	Integer	ID of the job

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not Found	—
`409`	Conflict	—

Retain job artifacts

POST /api/v4/projects/{id}/jobs/{job_id}/artifacts/keep

Retains job artifacts. Prevents artifacts for a job from being automatically deleted when they reach their expiration date.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`job_id` Path, required	Integer	ID of the job

Responses

Code	Description	Schema
`201`	Created	APIEntitiesCiJob
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

List all files in an artifacts archive

GET /api/v4/projects/{id}/jobs/{job_id}/artifacts/tree

Lists all files in a specified artifacts archive without extracting them.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`job_id` Path, required	Integer	ID of the job Example: `42`
`path` Query	String	Path to browse in the artifacts archive. Defaults to the root directory Default: `` Example: `coverage/reports`
`recursive` Query	Boolean	If `true`, returns all entries recursively Default: `false` Example: `false`
`job_token` Query	String	CI/CD job token for multi-project pipelines. Premium and Ultimate only
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCiJobArtifactEntry
`400`	Bad Request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Download a specific file from artifacts archive

GET /api/v4/projects/{id}/jobs/{job_id}/artifacts/{artifact_path}

This feature was introduced in GitLab 10.0

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`job_id` Path, required	Integer	ID of the job
`artifact_path` Path, required	String	Path to a file inside the artifacts archive
`job_token` Query	String	CI/CD job token for multi-project pipelines. Premium and Ultimate only

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiJob

Property	Type	Description
`allow_failure`	Boolean	—
`archived`	Boolean	Example: `false`
`artifacts`	Array of APIEntitiesCiJobArtifact	—
`artifacts_expire_at`	String (date-time)	Example: `2016-01-19T09:05:50.355Z`
`artifacts_file`	APIEntitiesCiJobArtifactFile	—
`commit`	APIEntitiesCommit	—
`coverage`	Number (float)	Example: `98.29`
`created_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`duration`	Number (float)	Time spent running Example: `0.465`
`erased_at`	String (date-time)	Example: `2015-12-24T18:00:29.728Z`
`failure_reason`	String	Example: `script_failure`
`finished_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`id`	Integer (int64)	Example: `1`
`name`	String	Example: `deploy_to_production`
`pipeline`	APIEntitiesCiPipelineBasic	—
`project`	Object	—
`project.ci_job_token_scope_enabled`	String	Example: `false`
`queued_duration`	Number (float)	Time spent enqueued Example: `0.123`
`ref`	String	Example: `main`
`runner`	APIEntitiesCiRunner	—
`runner_manager`	APIEntitiesCiRunnerManager	—
`stage`	String	Example: `deploy`
`started_at`	String (date-time)	Example: `2015-12-24T17:54:30.733Z`
`status`	String	Example: `waiting_for_resource`
`tag`	Boolean	—
`tag_list`	Array of strings	Example: `["ubuntu18","docker runner"]`
`user`	APIEntitiesUser	—
`web_url`	String	Example: `https://example.com/foo/bar/-/jobs/1`

APIEntitiesCiJobArtifact

Property	Type	Description
`file_format`	String	Allowed values: `raw`, `zip`, `gzip` Example: `zip`
`file_type`	String	Allowed values: `archive`, `metadata`, `trace`, `junit`, `sast`, `dependency_scanning`, `container_scanning`, `dast`, `codequality`, `license_scanning`, `performance`, `metrics`, `metrics_referee`, `network_referee`, `lsif`, `dotenv`, `cobertura`, `terraform`, `accessibility`, `cluster_applications`, `secret_detection`, `requirements`, `coverage_fuzzing`, `browser_performance`, `load_performance`, `api_fuzzing`, `cluster_image_scanning`, `cyclonedx`, `requirements_v2`, `annotations`, `repository_xray`, `jacoco`, `sarif` Example: `archive`
`filename`	String	Example: `artifacts.zip`
`size`	Integer	Example: `1000`

APIEntitiesCiJobArtifactEntry

Property	Type	Description
`mode`	String	Example: `100644`
`name`	String	Example: `index.html`
`path`	String	Example: `coverage/index.html`
`size`	Integer	Example: `12345`
`type`	String	Allowed values: `file`, `directory` Example: `file`

APIEntitiesCiJobArtifactFile

Property	Type	Description
`filename`	String	Example: `artifacts.zip`
`size`	Integer	Example: `1000`

APIEntitiesCiPipelineBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`status`	String	Example: `success`
`updated_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`

APIEntitiesCiRunner

Property	Type	Description
`active`	Boolean	Example: `true`
`created_at`	String (date-time)	Example: `2025-05-03T00:00:00.000Z`
`created_by`	APIEntitiesUserBasic	—
`description`	String	Example: `test-1-20150125`
`id`	Integer (int64)	Example: `8`
`ip_address`	String	Example: `127.0.0.1`
`is_shared`	Boolean	Example: `true`
`job_execution_status`	String	Allowed values: `active`, `idle` Example: `idle`
`name`	String	Example: `test`
`online`	Boolean	Example: `true`
`paused`	Boolean	Example: `false`
`runner_type`	String	Allowed values: `instance_type`, `group_type`, `project_type` Example: `instance_type`
`status`	String	Example: `online`

APIEntitiesCiRunnerManager

Property	Type	Description
`architecture`	String	Example: `amd64`
`contacted_at`	String	Example: `2023-10-24T01:27:06.549Z`
`created_at`	String	Example: `2023-10-24T01:27:06.549Z`
`id`	Integer (int64)	Example: `8`
`ip_address`	String	Example: `127.0.0.1`
`job_execution_status`	String	Allowed values: `active`, `idle` Example: `idle`
`platform`	String	Example: `linux`
`revision`	String	Example: `91a27b2a`
`status`	String	Example: `online`
`system_id`	String	Example: `runner-1`
`version`	String	Example: `16.11.0`

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesUser

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`bio`	String	—
`bot`	Boolean	—
`created_at`	String	—
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`discord`	String	—
`followers`	String	—
`following`	String	—
`github`	String	—
`id`	Integer (int64)	Example: `1`
`is_followed`	String	—
`job_title`	String	—
`linkedin`	String	—
`local_time`	String	—
`location`	String	—
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`organization`	String	—
`pronouns`	String	—
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`twitter`	String	—
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`
`website_url`	String	—
`work_information`	String	—

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

Delete all job artifacts in a project

Retrieve job artifacts

Download a specific file from artifacts archive from a ref

Download an artifact from a job

Delete job artifacts

Retain job artifacts

List all files in an artifacts archive

Download a specific file from artifacts archive

Schemas

APIEntitiesCiJob

APIEntitiesCiJobArtifact

APIEntitiesCiJobArtifactEntry

APIEntitiesCiJobArtifactFile

APIEntitiesCiPipelineBasic

APIEntitiesCiRunner

APIEntitiesCiRunnerManager

APIEntitiesCommit

APIEntitiesCustomAttribute

APIEntitiesUser

APIEntitiesUserBasic

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC compliance report

Thank you

Error

Request partner program details

Request received

Error