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.

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 request

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.