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	The 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	The ID or URL-encoded path of the project
`ref_name` Path, required	String	Branch or tag name in repository. `HEAD` or `SHA` references are not supported
`job` Query, required	String	The name of the job
`job_token` Query	String	To be used with triggers for multi-project pipelines, available only on Premium and Ultimate tiers
`search_recent_successful_pipelines` Query	Boolean	Search across recent successful pipelines instead of just the latest one 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	The ID or URL-encoded path of the project
`ref_name` Path, required	String	Branch or tag name in repository. `HEAD` or `SHA` references are not supported
`job` Query, required	String	The name of the job
`artifact_path` Path, required	String	Path to a file inside the artifacts archive
`job_token` Query	String	To be used with triggers for multi-project pipelines, available only on Premium and Ultimate tiers
`search_recent_successful_pipelines` Query	Boolean	Search across recent successful pipelines instead of just the latest one 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	The ID or URL-encoded path of the project
`job_id` Path, required	Integer	The ID of a job
`file_type` Query	String	The type of artifact to download. Defaults to the job artifacts archive 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	To be used with triggers for multi-project pipelines, available only on Premium and Ultimate tiers
`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	The ID or URL-encoded path of the project
`job_id` Path, required	Integer	The ID of a 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	The ID or URL-encoded path of the project
`job_id` Path, required	Integer	The ID of a 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	The ID or URL-encoded path of the project
`job_id` Path, required	Integer	ID of a job Example: `42`
`path` Query	String	Path to browse in the artifacts archive. Defaults to root directory Default: `` Example: `coverage/reports`
`recursive` Query	Boolean	If `true`, return 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	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	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	The ID or URL-encoded path of the project
`job_id` Path, required	Integer	The ID of a job
`artifact_path` Path, required	String	Path to a file inside the artifacts archive
`job_token` Query	String	To be used with triggers for multi-project pipelines, available only on Premium and Ultimate tiers

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