---
title: "Start Garbage Collection"
method: POST
path: "/v2/registry/{registry_name}/garbage-collection"
tags: ["DigitalOcean-public.v2-new_Container Registry"]
---

# Start Garbage Collection

`POST /v2/registry/{registry_name}/garbage-collection`

Garbage collection enables users to clear out unreferenced blobs (layer &
manifest data) after deleting one or more manifests from a repository. If
there are no unreferenced blobs resulting from the deletion of one or more
manifests, garbage collection is effectively a noop.
[See here for more information](https://docs.digitalocean.com/products/container-registry/how-to/clean-up-container-registry/)
about how and why you should clean up your container registry periodically.

To request a garbage collection run on your registry, send a POST request to
`/v2/registry/$REGISTRY_NAME/garbage-collection`. This will initiate the
following sequence of events on your registry.

* Set the registry to read-only mode, meaning no further write-scoped
  JWTs will be issued to registry clients. Existing write-scoped JWTs will
  continue to work until they expire which can take up to 15 minutes.
* Wait until all existing write-scoped JWTs have expired.
* Scan all registry manifests to determine which blobs are unreferenced.
* Delete all unreferenced blobs from the registry.
* Record the number of blobs deleted and bytes freed, mark the garbage
  collection status as `success`.
* Remove the read-only mode restriction from the registry, meaning write-scoped
  JWTs will once again be issued to registry clients.

## Path parameters

- `registry_name` string, required

## Request body

- RegistryRunGc
  - `type` 'untagged manifests only' | 'unreferenced blobs only' | 'untagged manifests and unreferenced blobs' — Type of the garbage collection to run against this registry

## Response `201`

The response will be a JSON object with a key of `garbage_collection`. This will be a json object with attributes representing the currently-active garbage collection.

- object
  - `garbage_collection` GarbageCollection
    - `uuid` string — A string specifying the UUID of the garbage collection.
    - `registry_name` string — The name of the container registry.
    - `status` 'requested' | 'waiting for write JWTs to expire' | 'scanning manifests' | 'deleting unreferenced blobs' | 'cancelling' | 'failed' | 'succeeded' | 'cancelled' — The current status of this garbage collection.
    - `created_at` string, date-time — The time the garbage collection was created.
    - `updated_at` string, date-time — The time the garbage collection was last updated.
    - `blobs_deleted` integer — The number of blobs deleted as a result of this garbage collection.
    - `freed_bytes` integer — The number of bytes freed as a result of this garbage collection.

## Other responses

- `401` — Authentication failed due to invalid credentials.
- `404` — The resource was not found.
- `429` — The API rate limit has been exceeded.
- `500` — There was a server error.
- `default` — There was an unexpected error.

---

[API](https://skmtc.net/digitalocean/apis/digitalocean-api.md) · [All operations](https://skmtc.net/digitalocean/apis/digitalocean-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/digitalocean/digitalocean-api/revisions/cb3bf9b21459/schema)