> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/storage-management-api.md).

# Storage Management API

Read and update retention and cold-storage policies for a backend.

### Authentication and permissions

Use an [API key](https://docs.groundcover.com/administer/api-keys.md) in `Authorization: Bearer <YOUR_API_KEY>` and select the backend with `X-Backend-Id: <YOUR_BACKEND_ID>`. Use your own API base URL for a self-hosted deployment.

**Admin required:** updating policies with POST or PUT. Listing and reading policies require backend access but do not require Admin permissions.

This API is available for supported BYOC backends. Unsupported backends can return HTTP 404.

### Endpoints

| Method | Endpoint                              | Purpose                                                  |
| ------ | ------------------------------------- | -------------------------------------------------------- |
| GET    | `/api/storage-management`             | List policies.                                           |
| GET    | `/api/storage-management/{data_type}` | Read a single policy and its current version.            |
| PUT    | `/api/storage-management/{data_type}` | **Admin required.** Replace an existing policy.          |
| POST   | `/api/storage-management/{data_type}` | **Admin required.** Alias for the same update operation. |

POST does not bypass the existing-policy or version checks. There is no DELETE operation.

### Storage Management categories

The four categories shown in **Settings → Storage Management** map to these API policy identifiers:

| UI category | API `data_type` | Retention applies to                                                                                                           |
| ----------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Logs        | `logs`          | Log records and related log storage.                                                                                           |
| Traces      | `traces`        | Trace and span records and related trace storage.                                                                              |
| Events      | `events`        | Event records, plus RUM events, RUM sessions and session replay.                                                               |
| APM         | `measurements`  | APM measurements and rollups, infrastructure measurements, database statement measurements and pipeline processing statistics. |

Use `/api/storage-management/measurements` for the APM category; `apm` is not an API `data_type`. The datasets grouped under Events and APM share their category's default retention. They do not have separate retention controls through these four categories. Event custom rules apply to event records, while RUM events, sessions and session replay use the default Events retention.

APM retention is separate from metrics time-series retention. See [Storage Management](https://docs.groundcover.com/operate/storage-management.md) for guidance on changing metrics retention.

### Read policies

```bash
curl --request GET 'https://api.groundcover.com/api/storage-management' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

```bash
curl --request GET 'https://api.groundcover.com/api/storage-management/logs' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>'
```

A single-policy response contains `data_type`, `retention`, `version`, `created_by`, `created_timestamp`, and optional `uuid`, `cold_volume`, `cold_move_duration`, and `custom_rules`. Listing returns an array of policies.

The list can also contain policy identifiers for additional backend datasets. These are separate backend policies, not extra UI categories or aliases for Logs, Traces, Events or APM. For example, `traces_interactions` is separate from `traces`, and `metrics_metadata` covers metric discovery metadata rather than metric samples. Changing one of the four category policies does not update these other policies. Use GET to discover which policies exist on your backend instead of assuming every accepted identifier has a policy.

### Update a policy

| Field                | Type    | Required | Description                                                                 |
| -------------------- | ------- | -------- | --------------------------------------------------------------------------- |
| `retention`          | string  | Yes      | Positive duration such as `30d`, `2w`, `12h`, `1M` or `1y`.                 |
| `version`            | integer | Yes      | Current policy version from GET. Used for optimistic concurrency.           |
| `cold_volume`        | string  | No       | Configured cold-storage volume. Must be supplied with `cold_move_duration`. |
| `cold_move_duration` | string  | No       | Duration before moving data to cold storage.                                |
| `custom_rules`       | array   | No       | Per-filter retention rules, supported only for logs, traces and events.     |

Each custom rule has `name`, `retention`, and `filters` (a gcQL filter expression without pipe operations). Names must be unique and contain only letters, numbers, underscores and hyphens. `created_by` is set from the authenticated caller.

Read the current policy first. This example uses `jq` to preserve its policy fields and current version while changing retention. Install `jq` before running it.

```bash
curl --fail-with-body 'https://api.groundcover.com/api/storage-management/logs'   --header 'Authorization: Bearer <YOUR_API_KEY>'   --header 'X-Backend-Id: <YOUR_BACKEND_ID>'   --output logs-policy.json

jq '{retention: "30d", version, cold_volume, cold_move_duration, custom_rules: (.custom_rules // [])}'   logs-policy.json > logs-policy-update.json

curl --request PUT 'https://api.groundcover.com/api/storage-management/logs'   --header 'Authorization: Bearer <YOUR_API_KEY>'   --header 'X-Backend-Id: <YOUR_BACKEND_ID>'   --header 'Content-Type: application/json'   --data-binary @logs-policy-update.json
```

HTTP 200 returns the resulting policy with its new version. HTTP 409 means another request changed the policy: fetch it again, reconcile your changes, and retry using the new version. HTTP 400 indicates invalid duration, data type or custom rules; HTTP 404 can indicate a missing policy or unsupported backend.

Reducing retention can expire stored data earlier. Review the entire resulting policy before submitting it, including custom rules and cold-storage settings.

See [Storage Management](https://docs.groundcover.com/operate/storage-management.md) for policy behavior.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/storage-management-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
