# Filter Presets API

Source: https://userguide.qualytics.io/explore/filtering-controls/filter-presets/api/

The Filter Presets API allows you to create, list, update, and delete filter presets programmatically.

> **Tip**
>
> For complete API documentation, including request/response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs).

All endpoints are served from your Qualytics deployment (e.g., `https://your-instance.qualytics.io`). The paths below include the `/api` prefix.

---

## List Filter Presets (Paginated)

Retrieve a paginated list of filter presets visible to the current user.

**Endpoint**: `GET /api/filter-presets`

**Permission**: Member user role or higher

**Query Parameters**:

| Parameter | Type | Description |
| --- | --- | --- |
| `name` | string | Partial-match filter on preset name. |
| `sort_name` | string | Sort by name: `asc` or `desc`. |
| `sort_created` | string | Sort by creation date: `asc` or `desc`. |
| `size` | integer | Page size (default: 50). |
| `page` | integer | Page number. |

Presets that include any datastore the caller cannot access are excluded from the response.

---

## List Filter Presets (Flat)

Retrieve a flat list of all filter presets visible to the current user, sorted by name. Intended for populating dropdowns.

**Endpoint**: `GET /api/filter-presets/listing`

**Permission**: Member user role or higher

Presets that include any datastore the caller cannot access are excluded from the response.

---

## Get a Filter Preset

Retrieve a single filter preset by ID.

**Endpoint**: `GET /api/filter-presets/{id}`

**Permission**: Member user role or higher. The caller must have access to all datastores referenced by the preset.

The response includes a `can_edit` boolean indicating whether the caller has permission to modify the preset.

**Errors**:

- `404 Not Found`: The preset does not exist or its datastores are outside the caller's team access.

---

## Create a Filter Preset

Create a new filter preset.

**Endpoint**: `POST /api/filter-presets`

**Permission**: Member user role or higher

**Request Body**:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | Yes | Preset name. Must be unique across the workspace. Maximum 255 characters. |
| `description` | string | No | Optional description. |
| `datastore_ids` | array of integers | No | Datastore IDs to include. The caller must have team access to all listed datastores. |
| `tag_names` | array of strings | No | Tag names to include. |
| `timeframe` | string | No | Default timeframe (`week`, `month`, `quarter`, `year`). |

> **Example: Example request**
>
> ```bash
> curl -X POST "https://your-instance.qualytics.io/api/filter-presets" \
>   -H "Authorization: Bearer YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "name": "Critical Production",
>     "description": "Datastores and tags for production-critical assets",
>     "datastore_ids": [1, 2, 3],
>     "tag_names": ["production", "critical"],
>     "timeframe": "month"
>   }'
> ```

**Errors**:

- `404 Not Found`: A referenced `datastore_id` or `tag_name` does not exist.
- `403 Forbidden`: One or more `datastore_ids` are not accessible to the caller.
- `409 Conflict`: A preset with the same name already exists.

---

## Update a Filter Preset

Update an existing filter preset. The update is a partial merge; fields not included in the request are left untouched.

**Endpoint**: `PUT /api/filter-presets/{id}`

**Permission**: Member user role or higher. Members can only update presets they created. Manager and Admin can update any visible preset.

The `last_editor` field updates on every successful call, even when no real change is made. Providing an empty array for `datastore_ids` or `tag_names` explicitly clears that collection on the preset.

**Errors**:

- `404 Not Found`: The preset does not exist or its datastores are outside the caller's team access.
- `403 Forbidden`: The caller does not have permission to modify this preset.
- `409 Conflict`: Renaming the preset to a name that already exists.

---

## Delete a Filter Preset

Delete a filter preset.

**Endpoint**: `DELETE /api/filter-presets/{id}`

**Permission**: Member user role or higher. Members can only delete presets they created. Manager and Admin can delete any visible preset.

Deletion is permanent. Any users actively using the preset (via the `?filter=<id>` URL parameter or their persisted selection) have their selection cleared and the Explore page returns to the default unfiltered view on their next page interaction.

**Errors**:

- `404 Not Found`: The preset does not exist or its datastores are outside the caller's team access.
- `403 Forbidden`: The caller does not have permission to delete this preset.

---

## Get Insights for a Filter Preset

Load Explore Insights data filtered by a preset's datastores and tags.

**Endpoint**: `GET /api/filter-presets/{id}/insights`

**Permission**: Member user role or higher. The caller must have access to all datastores referenced by the preset.

**Query Parameters**:

| Parameter | Type | Description |
| --- | --- | --- |
| `timeframe` | string | Override the preset's saved timeframe (`week`, `month`, `quarter`, `year`). |
| `offset` | integer | Timezone offset in minutes. |

The endpoint applies the preset's saved datastores and tags as filters, uses the preset's `timeframe` (or a query-param override), and uses the current date as the report date.

**Errors**:

- `404 Not Found`: The preset does not exist or its datastores are outside the caller's team access.

*Last updated: July 7, 2026.*
