Download GitLab CI job artifacts via the REST API — by job ID, by the latest successful pipeline for a ref, as a single extracted file, and manage their retention.
domain: docs.gitlab.com · 8 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
To download the full artifacts archive for a known job, GET https://gitlab.example.com/api/v4/projects/:id/jobs/:job_id/artifacts with --location (GitLab.com may redirect through a CDN); returns 200 and streams the zip archive.
To get artifacts from the latest successful pipeline for a branch/tag without knowing the job_id, GET https://gitlab.example.com/api/v4/projects/:id/jobs/artifacts/:ref_name/download?job=job_name (e.g. ref_name=main&job=test); ref_name must be a branch or tag name, not HEAD or a SHA — for merge request pipelines use refs/merge-requests/:iid/head.
Optionally add search_recent_successful_pipelines=true to search up to the 100 most recent successful pipelines for that ref instead of only the latest one.
To download one file out of the archive without unzipping, GET .../jobs/:job_id/artifacts/*artifact_path (by job_id) or GET .../jobs/artifacts/:ref_name/raw/*artifact_path?job=job_name (by ref); the file is extracted server-side and streamed.
POST https://gitlab.example.com/api/v4/projects/:id/jobs/:job_id/artifacts/keep to prevent a job's artifacts from being auto-deleted when they reach their expiration date.
DELETE https://gitlab.example.com/api/v4/projects/:id/jobs/:job_id/artifacts to permanently delete a job's artifacts (requires Maintainer or Owner role); this does not delete the job log — use the erase-a-job endpoint for that.
In CI jobs, pass job_token=$CI_JOB_TOKEN instead of a PRIVATE-TOKEN header for cross-project artifact downloads (Premium/Ultimate only).
Docs: https://docs.gitlab.com/api/job_artifacts/
Known gotchas
Artifacts are auto-deleted after they expire — call the keep endpoint before expiration if you need them retained; there is no documented way to change expire_in via this API after upload.
The by-ref download requires a completed pipeline with success status; if it includes manual jobs, they must have completed successfully or have allow_failure: true, or the lookup fails.
HEAD/SHA references are not accepted for the by-ref download and by-ref raw-file endpoints — only branch or tag names (or refs/merge-requests/:iid/head).
Use --location with curl on GitLab.com since artifact downloads may redirect through a CDN.
Deleting artifacts via DELETE requires Maintainer or Owner role on the project, and deleted artifacts cannot be recovered.
job_token-based cross-project artifact downloads are Premium and Ultimate only.
Give your agent this knowledge — and 18,000+ more routes
One MCP install gives any agent live access to the full route map across 6,000+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?