---
title: "Refine your Cloudsmith Retention Rules with Package Search Syntax"
description: "Cloudsmith now allows you to use a flexible package search syntax via the Cloudsmith API to create highly targeted retention policies. Filter packages by tags, versions, downloads, and more, enabling precise control over which packages are kept or removed."
canonical_url: "https://cloudsmith.com/changelog/keep-only-what-matters-using-search-based-retention-rules"
last_updated: "2025-06-19T14:09:40.219Z"
---
# Refine your Cloudsmith Retention Rules with Package Search Syntax

You can now use Cloudsmith’s [package search syntax]() to refine the scope of your repository's retention rules when configuring them via the [Cloudsmith API. ]()This flexible query language lets you filter packages by tag, version, downloads, and more, making it easier to target exactly which packages to keep or remove.

By using the `retention_package_query_string` field when setting up your repository’s retention rules, you can apply policies to a specific subset of packages within the repository, such as:

- Packages with no tags
- Packages without a specific tag
- Packages with fewer than 10 downloads

You can include multiple search filters, which work alongside existing configuration options like age limits, to enable smarter and more tailored retention policies. For example:

- Delete packages that are older than 30 days AND have no tags AND have never been downloaded.

### Sample query

Here is a sample query that deletes packages older than 180 days that **do not** have a "production" tag:

```json
{
  "_key": "d21794b016cf",
  "_type": "code",
  "code": "curl --request PATCH \\\n     --url https://api.cloudsmith.io/v1/repos/cloudsmith-test/acme-prod/retention/ \\\n     --header 'X-Api-Key: test-key' \\\n     --header 'accept: application/json' \\\n     --header 'content-type: application/json' \\\n     --data '\n{\n  \"retention_enabled\": true,\n  \"retention_days_limit\": 180,\n  \"retention_package_query_string\": \"tag:~production\"\n}",
  "filename": null,
  "language": "shell",
  "markDefs": null
}
```

### What’s Next

We’re actively working on adding support for search-based retention rules to both the Cloudsmith web UI and the Terraform Provider, so you’ll be able to configure them wherever you work.



In the meantime, check out [Retention Rules](https://help.cloudsmith.io/docs/retention-rules) for more information on configuring package retention rules for your Cloudsmith repositories.