diff --git a/docs/common-workflows/analytics/manage-selectors/manage-selectors.md b/docs/common-workflows/analytics/manage-selectors/manage-selectors.md
index ae27497d6..b095e8e2a 100644
--- a/docs/common-workflows/analytics/manage-selectors/manage-selectors.md
+++ b/docs/common-workflows/analytics/manage-selectors/manage-selectors.md
@@ -5,13 +5,17 @@ description: The Strategy RESTful server supports different types of selectors,
The Strategy RESTful server supports different types of selectors, similar to the function in Library Web.
-The following five selector types are supported:
+The following selector types are supported (depending on the product version):
- Attribute qualification selector
- Attribute element list selector
- Metric qualification selector
- Object replacement selector
- Visualization as filter
+- Parameter selector (MicroStrategy 2021 Update 12 or later)
+ - Element list parameter selector
+ - Object parameter selector
+ - Value parameter selector
You can use the following APIs to set the different types of selectors and view selector definitions:
@@ -36,7 +40,7 @@ The following section outlines a summary of the compatibility.
### Compatibility prior to MicroStrategy 2021 Update 1
-For library versions prior to MicroStrategy 2021 Update 1:
+For Library versions prior to MicroStrategy 2021 Update 1:
- The behavior remains the same for all Intelligence Server versions.
- The expected behavior for the GET Filter API is that the fetched filter definition json returns the chapter-level selector key, name, and summary.
@@ -46,10 +50,10 @@ For library versions prior to MicroStrategy 2021 Update 1:
### Compatibility on and after MicroStrategy 2021 Update 1
-For library versions on and after MicroStrategy 2021 Update 1, the behavior changes based on the Intelligence Server version.
+For Library versions on and after MicroStrategy 2021 Update 1, the behavior changes based on the Intelligence Server version.
- For Intelligence Server versions prior to MicroStrategy 2021 Update 1
- - The expected behavior for the GET filter API is that the fetched filter definition json is missing information for visualization as filter and dataset name for dataset. Returns the definition of the following selector types:
+ - The expected behavior for the GET Filter API is that the fetched filter definition json is missing information for visualization as filter and dataset name for dataset. Returns the definition of the following selector types:
- Attribute element list selector
- Attribute qualification selector
- Metric qualification selector
@@ -61,7 +65,7 @@ For library versions on and after MicroStrategy 2021 Update 1, the behavior chan
- Object replacement selector(Attribute/metric selector)
- Visualization as filter
- For Intelligence Server versions on and after MicroStrategy 2021 Update 1
- - The expected behavior for the GET filter API is that the fetched filter definition json is complete and returns the definition of the following selector types:
+ - The expected behavior for the GET Filter API is that the fetched filter definition json is complete and returns the definition of the following selector types:
- Attribute element list selector
- Attribute qualification selector
- Metric qualification selector
@@ -74,6 +78,15 @@ For library versions on and after MicroStrategy 2021 Update 1, the behavior chan
- Object replacement selector(Attribute/metric selector)
- Visualization as filter
+### Compatibility on and after MicroStrategy 2021 Update 12
+
+For Library and Intelligence Server versions on and after MicroStrategy 2021 Update 12, both the GET Filter API and the Setting Filter API are extended to support parameter selectors in addition to the existing selector types.
+
+- The following parameter selector types are supported:
+ - Element list parameter selector
+ - Object parameter selector
+ - Value parameter selector
+
## How to use selector consumption APIs
The diagrams below outlines common workflows for using APIs for dashboard selector functionalities.
diff --git a/docs/common-workflows/analytics/manage-selectors/retrieve-a-selectors-definition.md b/docs/common-workflows/analytics/manage-selectors/retrieve-a-selectors-definition.md
index 047a31ea1..f2ed86f36 100644
--- a/docs/common-workflows/analytics/manage-selectors/retrieve-a-selectors-definition.md
+++ b/docs/common-workflows/analytics/manage-selectors/retrieve-a-selectors-definition.md
@@ -18,17 +18,105 @@ This endpoint fetches a selector's definition and dataset information of a dashb
Output example for a dashboard and dashboard instance definition
```json
- { "id": "D29DC6464099A518DE19FEA4C25D346B", "name": "temp Dossier", "hasPrompt": false, "chapters": [ { "key": "K36", "name": "Chapter 1", "pages": [ { "key": "K53", "name": "Page 1", "visualizations": [ { "key": "K52", "name": "Visualization 1", "filteredTargetVisualizations": [ { "key": "W65" } ] }, { "key": "W62", "name": "Visualization 2" }, { "key": "W65", "name": "Visualization 3" } ], "inCanvasSelectors": [] } ], "filters": [ { "key": "W134", "name": "Cost", "summary": "((Cost Between 5707743.0 And 21191039.0))", "source": { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "type": 4 }, "synchronizedAcrossChapter":false "unset": false, "include": true, "multiSelected": true, "hasAllOption": true, "expression": { "operator": "And", "operands": [ { "operator": "Between", "operands": [ { "type": "metric", "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "name": "Cost" }, { "type": "constant", "dataType": "Real", "value": "5707743" }, { "type": "constant", "dataType": "Real", "value": "21191039" } ] } ] }, "selections": [] }, { "key": "W138", "name": "Category", "summary": "Category In List Electronics", "source": { "id": "8D679D3711D3E4981000E787EC6DE8A4", "type": 12 }, "unset": false, "include": true, "multiSelected": true, "hasAllOption": true, "selections": [ { "id": "h2;8D679D3711D3E4981000E787EC6DE8A4", "name": "Electronics" } ] } ] } ], "datasets": [ { "name": "8DFA1ABC41C2F43530645FA90B80C745", "id": "New Dataset 1", "availableObjects": [ { "id": "8D679D3711D3E4981000E787EC6DE8A4", "name": "Category", "type": "attribute", "forms": [ { "id": "CCFBE2A5EADB4F50941FB879CCF1721C", "name": "DESC" } ] }, { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "name": "Cost", "type": "metric" } ] } ] }
+ {
+ "id": "D29DC6464099A518DE19FEA4C25D346B",
+ "name": "temp Dossier",
+ "hasPrompt": false,
+ "chapters": [
+ {
+ "key": "K36",
+ "name": "Chapter 1",
+ "pages": [
+ {
+ "key": "K53",
+ "name": "Page 1",
+ "visualizations": [
+ {
+ "key": "K52",
+ "name": "Visualization 1",
+ "filteredTargetVisualizations": [{ "key": "W65" }]
+ },
+ { "key": "W62", "name": "Visualization 2" },
+ { "key": "W65", "name": "Visualization 3" }
+ ],
+ "inCanvasSelectors": []
+ }
+ ],
+ "filters": [
+ {
+ "key": "W134",
+ "name": "Cost",
+ "summary": "((Cost Between 5707743.0 And 21191039.0))",
+ "source": { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "type": 4 },
+ "synchronizedAcrossChapter": false,
+ "unset": false,
+ "include": true,
+ "multiSelected": true,
+ "hasAllOption": true,
+ "expression": {
+ "operator": "And",
+ "operands": [
+ {
+ "operator": "Between",
+ "operands": [
+ {
+ "type": "metric",
+ "id": "7FD5B69611D5AC76C000D98A4CC5F24F",
+ "name": "Cost"
+ },
+ { "type": "constant", "dataType": "Real", "value": "5707743" },
+ { "type": "constant", "dataType": "Real", "value": "21191039" }
+ ]
+ }
+ ]
+ },
+ "selections": []
+ },
+ {
+ "key": "W138",
+ "name": "Category",
+ "summary": "Category In List Electronics",
+ "source": { "id": "8D679D3711D3E4981000E787EC6DE8A4", "type": 12 },
+ "unset": false,
+ "include": true,
+ "multiSelected": true,
+ "hasAllOption": true,
+ "selections": [{ "id": "h2;8D679D3711D3E4981000E787EC6DE8A4", "name": "Electronics" }]
+ }
+ ]
+ }
+ ],
+ "datasets": [
+ {
+ "name": "8DFA1ABC41C2F43530645FA90B80C745",
+ "id": "New Dataset 1",
+ "availableObjects": [
+ {
+ "id": "8D679D3711D3E4981000E787EC6DE8A4",
+ "name": "Category",
+ "type": "attribute",
+ "forms": [{ "id": "CCFBE2A5EADB4F50941FB879CCF1721C", "name": "DESC" }]
+ },
+ { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "name": "Cost", "type": "metric" }
+ ]
+ }
+ ]
+ }
```
- Filter definition:
- - Element list selector (in chapter-level, in canvas)
+ - The examples below are independent selector object snippets from definition responses. Object names and IDs are illustrative and may differ across examples. Parameter selectors can share the same selectorType as non-parameter selectors:
+
+ - Element list parameter selectors use attribute_element_list, and object parameter selectors use object_replacement.
+ - Only value parameter selectors use value_parameter.
+
+ - Element list selector (in chapter-level, in canvas) or element list parameter selector (in chapter-level, in canvas)
- Output examples for an element list selector definition
+ Output examples for an element list (parameter) selector definition
Common attribute element list:
@@ -87,6 +175,38 @@ This endpoint fetches a selector's definition and dataset information of a dashb
}
```
+ Common element list parameter:
+
+ ```json
+ {
+ "key": "IGKD091F7A20147A4F1943537A36FDE1ED0",
+ "name": "Category Parameter",
+ "summary": "Category Parameter In List Books",
+ "source": {
+ "id": "8D679D3711D3E4981000E787EC6DE8A4",
+ "name": "Category",
+ "type": 12
+ },
+ "synchronizedAcrossChapter": true,
+ "selectorType": "attribute_element_list",
+ "displayStyle": "check_boxes",
+ "hasAllOption": true,
+ "targets": [],
+ "multiSelectionAllowed": true,
+ "selectionRequired": false,
+ "currentSelection": {
+ "selectionStatus": "included",
+ "allSelected": false,
+ "elements": [
+ {
+ "id": "h1;8D679D3711D3E4981000E787EC6DE8A4",
+ "name": "Books"
+ }
+ ]
+ }
+ }
+ ```
+
- Attribute qualification selector (in chapter-level, in canvas)
@@ -257,10 +377,37 @@ This endpoint fetches a selector's definition and dataset information of a dashb
- - Object replacement selector (in-canvas)
+ - Value parameter selector (in chapter-level, in canvas)
+
+
+ Output example for a value parameter selector definition
+
+ ```json
+ {
+ "key": "WF4E8A712EF9942989C3FA03EDBE22769",
+ "name": "Cost Value Parameter",
+ "summary": "Cost Value Parameter In List NONE",
+ "synchronizedAcrossChapter": true,
+ "selectorType": "value_parameter",
+ "displayStyle": "text_box",
+ "hasAllOption": false,
+ "targets": [],
+ "multiSelectionAllowed": false,
+ "currentSelection": {
+ "selectionStatus": "included",
+ "values": []
+ }
+ }
+ ```
+
+
+
+ - Object replacement selector (in-canvas) or object parameter selector (in chapter-level, in canvas)
- Output example for an object replacement selector definition
+ Output examples for an object replacement selector definition and an object parameter selector definition
+
+ Common object replacement selector:
```json
{
@@ -298,6 +445,51 @@ This endpoint fetches a selector's definition and dataset information of a dashb
}
```
+ Common object parameter selector:
+
+ ```json
+ {
+ "key": "WB255D7448AAE4A46BA68DA3E8EB9E51C",
+ "name": "Time Object Parameter",
+ "summary": "Time Object Parameter In List Year, Quarter",
+ "synchronizedAcrossChapter": true,
+ "selectorType": "object_replacement",
+ "displayStyle": "check_boxes",
+ "hasAllOption": false,
+ "targets": [],
+ "multiSelectionAllowed": true,
+ "currentSelection": {
+ "selectionStatus": "included",
+ "objectItems": [
+ {
+ "id": "U0C2C22CB4183D69EC1791D9EEAA52772;0C2C22CB4183D69EC1791D9EEAA52772",
+ "name": "Year"
+ },
+ {
+ "id": "U550D8DC747552CA13A939C843798EE1F;550D8DC747552CA13A939C843798EE1F",
+ "name": "Quarter"
+ }
+ ]
+ },
+ "availableObjectItems": [
+ {
+ "id": "U0C2C22CB4183D69EC1791D9EEAA52772;0C2C22CB4183D69EC1791D9EEAA52772",
+ "name": "Year"
+ },
+ {
+ "id": "U550D8DC747552CA13A939C843798EE1F;550D8DC747552CA13A939C843798EE1F",
+ "name": "Quarter"
+ },
+ {
+ "id": "U12811362465C929D0A27ED85E4F2ADD0;12811362465C929D0A27ED85E4F2ADD0",
+ "name": "Month"
+ }
+ ],
+ "parameterId": "6C812C1F62467971837A54B0B1397251",
+ "isParameterBased": true
+ }
+ ```
+
- Set visualization as filter
@@ -363,17 +555,103 @@ This endpoint fetches a selector's definition and dataset information from an ex
Output example for a dashboard and dashboard instance definition
```json
- { "id": "D29DC6464099A518DE19FEA4C25D346B", "name": "temp Dossier", "hasPrompt": false, "chapters": [ { "key": "K36", "name": "Chapter 1", "pages": [ { "key": "K53", "name": "Page 1", "visualizations": [ { "key": "K52", "name": "Visualization 1", "filteredTargetVisualizations": [ { "key": "W65" } ] }, { "key": "W62", "name": "Visualization 2" }, { "key": "W65", "name": "Visualization 3" } ], "inCanvasSelectors": [] } ], "filters": [ { "key": "W134", "name": "Cost", "summary": "((Cost Between 5707743.0 And 21191039.0))", "source": { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "type": 4 }, "synchronizedAcrossChapter":false "unset": false, "include": true, "multiSelected": true, "hasAllOption": true, "expression": { "operator": "And", "operands": [ { "operator": "Between", "operands": [ { "type": "metric", "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "name": "Cost" }, { "type": "constant", "dataType": "Real", "value": "5707743" }, { "type": "constant", "dataType": "Real", "value": "21191039" } ] } ] }, "selections": [] }, { "key": "W138", "name": "Category", "summary": "Category In List Electronics", "source": { "id": "8D679D3711D3E4981000E787EC6DE8A4", "type": 12 }, "unset": false, "include": true, "multiSelected": true, "hasAllOption": true, "selections": [ { "id": "h2;8D679D3711D3E4981000E787EC6DE8A4", "name": "Electronics" } ] } ] } ], "datasets": [ { "name": "8DFA1ABC41C2F43530645FA90B80C745", "id": "New Dataset 1", "availableObjects": [ { "id": "8D679D3711D3E4981000E787EC6DE8A4", "name": "Category", "type": "attribute", "forms": [ { "id": "CCFBE2A5EADB4F50941FB879CCF1721C", "name": "DESC" } ] }, { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "name": "Cost", "type": "metric" } ] } ] }
+ {
+ "id": "D29DC6464099A518DE19FEA4C25D346B",
+ "name": "temp Dossier",
+ "hasPrompt": false,
+ "chapters": [
+ {
+ "key": "K36",
+ "name": "Chapter 1",
+ "pages": [
+ {
+ "key": "K53",
+ "name": "Page 1",
+ "visualizations": [
+ {
+ "key": "K52",
+ "name": "Visualization 1",
+ "filteredTargetVisualizations": [{ "key": "W65" }]
+ },
+ { "key": "W62", "name": "Visualization 2" },
+ { "key": "W65", "name": "Visualization 3" }
+ ],
+ "inCanvasSelectors": []
+ }
+ ],
+ "filters": [
+ {
+ "key": "W134",
+ "name": "Cost",
+ "summary": "((Cost Between 5707743.0 And 21191039.0))",
+ "source": { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "type": 4 },
+ "synchronizedAcrossChapter": false,
+ "unset": false,
+ "include": true,
+ "multiSelected": true,
+ "hasAllOption": true,
+ "expression": {
+ "operator": "And",
+ "operands": [
+ {
+ "operator": "Between",
+ "operands": [
+ {
+ "type": "metric",
+ "id": "7FD5B69611D5AC76C000D98A4CC5F24F",
+ "name": "Cost"
+ },
+ { "type": "constant", "dataType": "Real", "value": "5707743" },
+ { "type": "constant", "dataType": "Real", "value": "21191039" }
+ ]
+ }
+ ]
+ },
+ "selections": []
+ },
+ {
+ "key": "W138",
+ "name": "Category",
+ "summary": "Category In List Electronics",
+ "source": { "id": "8D679D3711D3E4981000E787EC6DE8A4", "type": 12 },
+ "unset": false,
+ "include": true,
+ "multiSelected": true,
+ "hasAllOption": true,
+ "selections": [{ "id": "h2;8D679D3711D3E4981000E787EC6DE8A4", "name": "Electronics" }]
+ }
+ ]
+ }
+ ],
+ "datasets": [
+ {
+ "name": "8DFA1ABC41C2F43530645FA90B80C745",
+ "id": "New Dataset 1",
+ "availableObjects": [
+ {
+ "id": "8D679D3711D3E4981000E787EC6DE8A4",
+ "name": "Category",
+ "type": "attribute",
+ "forms": [{ "id": "CCFBE2A5EADB4F50941FB879CCF1721C", "name": "DESC" }]
+ },
+ { "id": "7FD5B69611D5AC76C000D98A4CC5F24F", "name": "Cost", "type": "metric" }
+ ]
+ }
+ ]
+ }
```
- Filter definition:
+ - The examples below are independent selector object snippets from definition responses. Object names and IDs are illustrative and may differ across examples. Parameter selectors can share the same selectorType as non-parameter selectors:
+ - Element list parameter selectors use attribute_element_list, and object parameter selectors use object_replacement.
+ - Only value parameter selectors use value_parameter.
- Element list selector (in chapter-level, in canvas)
- Output examples for an element list selector definition
+ Output examples for an element list (parameter) selector definition
Common attribute element list:
@@ -432,6 +710,38 @@ This endpoint fetches a selector's definition and dataset information from an ex
}
```
+ Common element list parameter:
+
+ ```json
+ {
+ "key": "IGKD091F7A20147A4F1943537A36FDE1ED0",
+ "name": "Category Parameter",
+ "summary": "Category Parameter In List Books",
+ "source": {
+ "id": "8D679D3711D3E4981000E787EC6DE8A4",
+ "name": "Category",
+ "type": 12
+ },
+ "synchronizedAcrossChapter": true,
+ "selectorType": "attribute_element_list",
+ "displayStyle": "check_boxes",
+ "hasAllOption": true,
+ "targets": [],
+ "multiSelectionAllowed": true,
+ "selectionRequired": false,
+ "currentSelection": {
+ "selectionStatus": "included",
+ "allSelected": false,
+ "elements": [
+ {
+ "id": "h1;8D679D3711D3E4981000E787EC6DE8A4",
+ "name": "Books"
+ }
+ ]
+ }
+ }
+ ```
+
- Attribute qualification selector (in chapter-level, in canvas)
@@ -602,10 +912,38 @@ This endpoint fetches a selector's definition and dataset information from an ex
- - Object replacement selector (in-canvas)
+ - Value parameter selector (in chapter-level, in canvas)
+
+
+ Output example for a value parameter selector definition
+ ```json
+ {
+ "key": "WF4E8A712EF9942989C3FA03EDBE22769",
+ "name": "Cost Value Parameter",
+ "summary": "Cost Value Parameter In List NONE",
+ "synchronizedAcrossChapter": true,
+ "selectorType": "value_parameter",
+ "displayStyle": "text_box",
+ "hasAllOption": false,
+ "targets": [
+ ],
+ "multiSelectionAllowed": false,
+ "currentSelection": {
+ "selectionStatus": "included",
+ "values": [
+ ]
+ }
+ }
+ ```
+
+
+
+ - Object replacement selector (in-canvas) or object parameter selector (in chapter-level, in canvas)
- Output example for an object replacement selector definition
+ Output examples for an object replacement selector definition and an object parameter selector definition
+
+ Common object replacement selector:
```json
{
@@ -643,6 +981,51 @@ This endpoint fetches a selector's definition and dataset information from an ex
}
```
+ Common object parameter selector:
+
+ ```json
+ {
+ "key": "WB255D7448AAE4A46BA68DA3E8EB9E51C",
+ "name": "Time Object Parameter",
+ "summary": "Time Object Parameter In List Year, Quarter",
+ "synchronizedAcrossChapter": true,
+ "selectorType": "object_replacement",
+ "displayStyle": "check_boxes",
+ "hasAllOption": false,
+ "targets": [],
+ "multiSelectionAllowed": true,
+ "currentSelection": {
+ "selectionStatus": "included",
+ "objectItems": [
+ {
+ "id": "U0C2C22CB4183D69EC1791D9EEAA52772;0C2C22CB4183D69EC1791D9EEAA52772",
+ "name": "Year"
+ },
+ {
+ "id": "U550D8DC747552CA13A939C843798EE1F;550D8DC747552CA13A939C843798EE1F",
+ "name": "Quarter"
+ }
+ ]
+ },
+ "availableObjectItems": [
+ {
+ "id": "U0C2C22CB4183D69EC1791D9EEAA52772;0C2C22CB4183D69EC1791D9EEAA52772",
+ "name": "Year"
+ },
+ {
+ "id": "U550D8DC747552CA13A939C843798EE1F;550D8DC747552CA13A939C843798EE1F",
+ "name": "Quarter"
+ },
+ {
+ "id": "U12811362465C929D0A27ED85E4F2ADD0;12811362465C929D0A27ED85E4F2ADD0",
+ "name": "Month"
+ }
+ ],
+ "parameterId": "6C812C1F62467971837A54B0B1397251",
+ "isParameterBased": true
+ }
+ ```
+
- Set visualization as filter
diff --git a/docs/common-workflows/analytics/manage-selectors/set-selector-type.md b/docs/common-workflows/analytics/manage-selectors/set-selector-type.md
index 165636da7..298d11a0b 100644
--- a/docs/common-workflows/analytics/manage-selectors/set-selector-type.md
+++ b/docs/common-workflows/analytics/manage-selectors/set-selector-type.md
@@ -9,10 +9,11 @@ You can set the different types of selector using the following requests.
This endpoint is used to execute a dashboard with specific filtering criteria applied in the current chapter. You can set the following selector types:
-- Element list selector (in chapter-level, in canvas)
+- Element list selector or element list parameter selector (in chapter-level, in canvas)
- Attribute qualification selector (in chapter-level, in canvas)
- Metric qualification selector (in chapter-level, in canvas)
-- Object replacement selector (in canvas)
+- Value parameter selector (in chapter-level, in canvas)
+- Object replacement selector (in canvas) or object parameter selector (in chapter-level, in canvas)
- Visualization as filter
You can also perform the following:
@@ -31,7 +32,7 @@ You can also perform the following:
Sample Input Body:
-- Element list selector:
+- Element list selector or element list parameter selector:
```json
{
@@ -119,7 +120,19 @@ Sample Input Body:
}
```
-- Object replacement selector:
+- Value parameter selector:
+
+ ```json
+ {
+ "key": "WF4E8A712EF9942989C3FA03EDBE22769",
+ "currentSelection": {
+ "selectionStatus": "included",
+ "values": ["1000"]
+ }
+ }
+ ```
+
+- Object replacement selector or object parameter selector:
```json
{
@@ -206,10 +219,11 @@ Sample Response Body:
This endpoint is used to execute a dashboard with specific filtering criteria applied in the current chapter. You can set the following selector types:
-- Element list selector (in chapter-level, in canvas)
+- Element list selector or element list parameter selector (in chapter-level, in canvas)
- Attribute qualification selector (in chapter-level, in canvas)
- Metric qualification selector (in chapter-level, in canvas)
-- Object replacement selector (in canvas)
+- Value parameter selector (in chapter-level, in canvas)
+- Object replacement selector (in canvas) or object parameter selector (in chapter-level, in canvas)
- Visualization as filter
You can also perform the following:
@@ -316,7 +330,19 @@ Sample Input Body:
}
```
-- Object replacement selector:
+- Value parameter selector:
+
+ ```json
+ {
+ "key": "WF4E8A712EF9942989C3FA03EDBE22769",
+ "currentSelection": {
+ "selectionStatus": "included",
+ "values": ["1000"]
+ }
+ }
+ ```
+
+- Object replacement selector or object parameter selector:
```json
{
@@ -392,7 +418,7 @@ Response Code: 204 (no content)
## API: [GET /api/dossiers/\{dossierId}/instances/\{instanceId}/elements](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Dossiers%20and%20Documents/getDossierDatasetFilterElements)
-This endpoint is used to fetch available elements for the element list selector.
+This endpoint is used to fetch available elements for an element list selector or an element list parameter selector.
### Functionality
diff --git a/docs/common-workflows/mosaic/retrieve-data-from-data-models/apply-parameters-to-a-data-model-instance.md b/docs/common-workflows/mosaic/retrieve-data-from-data-models/apply-parameters-to-a-data-model-instance.md
new file mode 100644
index 000000000..3abd959f4
--- /dev/null
+++ b/docs/common-workflows/mosaic/retrieve-data-from-data-models/apply-parameters-to-a-data-model-instance.md
@@ -0,0 +1,846 @@
+---
+title: Apply parameters to a data model instance
+description:
+ This workflow demonstrates how to retrieve the parameter definitions of a Mosaic data model, and
+ how to apply, retrieve, and change the parameter values of a data model instance using REST API.
+---
+
+
+
+:::info
+
+Get the authorization token needed to execute the request with
+[POST /api/auth/login](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Authentication/postLogin).
+
+Get the project ID from
+[GET /api/projects](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html#/Projects/getProjects_1).
+
+:::
+
+A Mosaic data model can expose parameters that its metrics consume at query time. This workflow
+sample demonstrates how to read the parameters a model defines, supply values for them when you
+create a cube instance, change those values afterward, and retrieve the data the new values
+produce.
+
+Parameters are _defined_ on the model and _given values_ on an instance, and two different requests
+report the two halves:
+
+- [GET /api/model/dataModels/\{dataModelId}/parameters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Data%20Models)
+ returns each parameter's **definition** — its datatype, and which values it will accept.
+- The cube instance requests below report and change the parameter **values** a particular instance
+ is currently using. They do not describe what a legal value is.
+
+Read the definitions first, so you know what each parameter accepts before you send a value for it.
+
+## Retrieve the parameter definitions from the model
+
+Retrieve the parameters the model defines, each with its datatype and the values it accepts. This
+request is made against the model itself, so it needs no cube instance and no changeset.
+
+The `information.subType` of a parameter gives its datatype, for example `prompt_double`,
+`prompt_long`, `prompt_string`, `prompt_date`, or `prompt_big_decimal`. The
+`restriction.allowedValueType` gives the kind of value the parameter accepts, and determines which
+other `restriction` fields are present:
+
+| `allowedValueType` | The parameter accepts | Other `restriction` fields |
+| ------------------ | ------------------------------------- | ------------------------------------------------------------- |
+| `user_input` | any value of the parameter's datatype | none |
+| `fixed_list` | only a value drawn from a fixed list | `values`, the list of allowed values |
+| `range` | only a value between two bounds | `min` and `max`, and `interval` when the model defines a step |
+
+The response is paged. `total` reports how many parameters the model defines, while `offset` and
+`limit` describe the page returned. Pass `offset` and `limit` as query parameters to page through
+them; the default `limit` of `-1` returns all of them.
+
+Endpoint:
+[GET /api/model/dataModels/\{dataModelId}/parameters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Data%20Models)
+
+Sample Request
+
+- Request Headers
+
+```http
+'Accept: application/json'
+'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7'
+'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+- Curl
+
+```bash
+curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/model/dataModels/8F4E447590CE457A983D5C3764486805/parameters' \
+--header 'Accept: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+Sample Response
+
+Both parameters of this model take any number the user supplies, so each one reports an
+`allowedValueType` of `user_input` and no further restriction.
+
+- Response Body:
+
+```json
+{
+ "offset": 0,
+ "limit": -1,
+ "total": 2,
+ "parameters": [
+ {
+ "information": {
+ "dateCreated": "2026-08-19T07:34:43.645Z",
+ "dateModified": "2026-08-19T07:34:43.645Z",
+ "versionId": "C390BE0F9F4275D4633DE69B25CCF94D",
+ "acg": 255,
+ "primaryLocale": "en-US",
+ "objectId": "314988F06296423EB33A7361A4EB126D",
+ "subType": "prompt_double",
+ "name": "minP",
+ "destinationFolderId": "4CDDE83E81EA47D8B451791C9DA87177"
+ },
+ "restriction": {
+ "allowedValueType": "user_input"
+ }
+ },
+ {
+ "information": {
+ "dateCreated": "2026-08-19T08:03:08.534Z",
+ "dateModified": "2026-08-19T08:03:08.534Z",
+ "versionId": "D0501562D44FAE3E226C4C9462A5594D",
+ "acg": 255,
+ "primaryLocale": "en-US",
+ "objectId": "DB8B46BC23444186B9D05D9D1E2D71A4",
+ "subType": "prompt_double",
+ "name": "maxP",
+ "destinationFolderId": "4CDDE83E81EA47D8B451791C9DA87177"
+ },
+ "restriction": {
+ "allowedValueType": "user_input"
+ }
+ }
+ ]
+}
+```
+
+- Response Code: 200 (Success: OK)
+
+A parameter restricted to a fixed list reports the values it accepts:
+
+```json
+{
+ "restriction": {
+ "allowedValueType": "fixed_list",
+ "values": [100, 200, 500]
+ }
+}
+```
+
+A parameter restricted to a range reports its bounds, and a step when the model defines one:
+
+```json
+{
+ "restriction": {
+ "allowedValueType": "range",
+ "min": 0,
+ "max": 1000,
+ "interval": 50
+ }
+}
+```
+
+Send a value that the parameter's `allowedValueType` does not permit and the request is refused, as
+shown in [Handle a rejected value](#handle-a-rejected-value).
+
+## Create a cube instance with parameters
+
+Supply the parameter values in the body of the create-instance request. The model is then executed
+once, with your values, instead of once with the model's defaults and again for each later change. A
+cube that is not a Mosaic data model ignores the `parameters` field.
+
+If a value is rejected, the whole request fails with a `400` and the instance, although created, is
+not returned and expires on its own.
+
+Endpoint:
+[POST /api/v2/cubes/\{dataModelId}/instances](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Cubes/createCubeInstance_1)
+
+Sample Request
+
+- Request Headers
+
+```http
+'Content-Type: application/json'
+'Accept: application/json'
+'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7'
+'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+- Request Body
+
+```json
+{
+ "parameters": [
+ { "id": "314988F06296423EB33A7361A4EB126D", "value": "200" },
+ { "id": "DB8B46BC23444186B9D05D9D1E2D71A4", "value": "900" }
+ ]
+}
+```
+
+- Curl
+
+```bash
+curl --location --request POST 'https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/cubes/8F4E447590CE457A983D5C3764486805/instances?limit=5' \
+--header 'Content-Type: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \
+--data '{
+ "parameters": [
+ { "id": "314988F06296423EB33A7361A4EB126D", "value": "200" },
+ { "id": "DB8B46BC23444186B9D05D9D1E2D71A4", "value": "900" }
+ ]
+}'
+```
+
+Sample Response
+
+The response is a regular cube instance result. The applied values appear in the `parameters` array, and the `data` reflects them: the metrics that consume `minP` and `maxP` are evaluated with the values you supplied.
+
+- Response Body:
+
+```json
+{
+ "name": "Airline Ticket Pricing Route Model",
+ "id": "8F4E447590CE457A983D5C3764486805",
+ "instanceId": "3055A8906D4A8D6582A0B3BD13319E65",
+ "status": 1,
+ "definition": {
+ "grid": {
+ "crossTab": false,
+ "metricsPosition": {
+ "axis": "columns",
+ "index": 0
+ },
+ "rows": [
+ {
+ "name": "From City",
+ "id": "B24BDFA9D7CB4F4FA9A8CF82FC55A59B",
+ "type": "attribute",
+ "forms": [
+ {
+ "id": "45C11FA478E745FEA08D781CEA190FE5",
+ "name": "ID",
+ "dataType": "integer",
+ "baseFormCategory": "ID",
+ "baseFormType": "number"
+ }
+ ],
+ "elements": [
+ {
+ "formValues": ["1"],
+ "id": "h1;B24BDFA9D7CB4F4FA9A8CF82FC55A59B"
+ },
+ {
+ "formValues": ["2"],
+ "id": "h2;B24BDFA9D7CB4F4FA9A8CF82FC55A59B"
+ },
+ {
+ "formValues": ["3"],
+ "id": "h3;B24BDFA9D7CB4F4FA9A8CF82FC55A59B"
+ }
+ ]
+ },
+ {
+ "name": "To City",
+ "id": "81E5474F4A314857B439BA11549500CC",
+ "type": "attribute",
+ "forms": [
+ {
+ "id": "45C11FA478E745FEA08D781CEA190FE5",
+ "name": "ID",
+ "dataType": "integer",
+ "baseFormCategory": "ID",
+ "baseFormType": "number"
+ }
+ ],
+ "elements": [
+ {
+ "formValues": ["2"],
+ "id": "h2;81E5474F4A314857B439BA11549500CC"
+ },
+ {
+ "formValues": ["3"],
+ "id": "h3;81E5474F4A314857B439BA11549500CC"
+ },
+ {
+ "formValues": ["1"],
+ "id": "h1;81E5474F4A314857B439BA11549500CC"
+ },
+ {
+ "formValues": ["6"],
+ "id": "h6;81E5474F4A314857B439BA11549500CC"
+ }
+ ]
+ }
+ ],
+ "columns": [
+ {
+ "name": "Metrics",
+ "id": "00000000000000000000000000000000",
+ "type": "templateMetrics",
+ "elements": [
+ {
+ "name": "advTicketMP",
+ "id": "FF7E9DB24B134A5A893534A466B12195",
+ "type": "metric",
+ "min": 990.0,
+ "max": 1280.0,
+ "dataType": "double",
+ "numberFormatting": {}
+ },
+ {
+ "name": "advTicketP",
+ "id": "93D34C27536A42078F867A55C4C0A077",
+ "type": "metric",
+ "min": -110.0,
+ "max": 180.0,
+ "dataType": "double",
+ "numberFormatting": {}
+ },
+ {
+ "name": "Ticket Price",
+ "id": "0D1A650A93CD4851AEA51949D4808701",
+ "type": "metric",
+ "min": 90,
+ "max": 380,
+ "dataType": "integer",
+ "numberFormatting": {
+ "category": 1,
+ "formatString": "#,##0",
+ "negativeType": 1
+ }
+ }
+ ]
+ }
+ ],
+ "sorting": {
+ "rows": [],
+ "columns": [],
+ "pageBy": []
+ },
+ "thresholds": []
+ }
+ },
+ "data": {
+ "currentPageBy": [],
+ "paging": {
+ "total": 10,
+ "current": 5,
+ "offset": 0,
+ "limit": 5
+ },
+ "headers": {
+ "rows": [
+ [0, 0],
+ [0, 1],
+ [1, 2],
+ [1, 3],
+ [2, 0]
+ ],
+ "columns": [[0, 1, 2]]
+ },
+ "metricValues": {
+ "raw": [
+ [1250.0, 150.0, 350],
+ [1050.0, -50.0, 150],
+ [1280.0, 180.0, 380],
+ [1150.0, 50.0, 250],
+ [1180.0, 80.0, 280]
+ ],
+ "formatted": [
+ ["1250", "150", "350"],
+ ["1050", "-50", "150"],
+ ["1280", "180", "380"],
+ ["1150", "50", "250"],
+ ["1180", "80", "280"]
+ ],
+ "extras": [
+ [{}, {}, {}],
+ [{}, {}, {}],
+ [{}, {}, {}],
+ [{}, {}, {}],
+ [{}, {}, {}]
+ ]
+ }
+ },
+ "promptOrdering": [],
+ "parameters": [
+ {
+ "id": "314988F06296423EB33A7361A4EB126D",
+ "name": "minP",
+ "value": "200"
+ },
+ {
+ "id": "DB8B46BC23444186B9D05D9D1E2D71A4",
+ "name": "maxP",
+ "value": "900"
+ }
+ ]
+}
+```
+
+- Response Code: 200 (Success: OK)
+
+## List the parameters of an instance
+
+List the parameters a Mosaic data model exposes on the instance you created, each with its object
+ID, its name, and its current value. The object ID is what identifies a parameter when you change
+its value.
+
+A parameter that has never been given a value, or that has been unset, has no `value` field in the
+response.
+
+This request reports the state of the instance only. To learn a parameter's datatype or which values
+it accepts, read its definition from the model, as shown in
+[Retrieve the parameter definitions from the model](#retrieve-the-parameter-definitions-from-the-model).
+
+Endpoint:
+[GET /api/v2/cubes/\{dataModelId}/instances/\{instanceId}/parameters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Cubes/getMosaicParameters)
+
+Sample Request
+
+- Request Headers
+
+```http
+'Accept: application/json'
+'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7'
+'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+- Curl
+
+```bash
+curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/cubes/8F4E447590CE457A983D5C3764486805/instances/3055A8906D4A8D6582A0B3BD13319E65/parameters' \
+--header 'Accept: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+Sample Response
+
+- Response Body:
+
+```json
+{
+ "parameters": [
+ {
+ "id": "314988F06296423EB33A7361A4EB126D",
+ "name": "minP",
+ "value": "200"
+ },
+ {
+ "id": "DB8B46BC23444186B9D05D9D1E2D71A4",
+ "name": "maxP",
+ "value": "900"
+ }
+ ]
+}
+```
+
+- Response Code: 200 (Success: OK)
+
+## Change the parameter values of an instance
+
+Apply values to any number of parameters in one request, and return the resulting parameters. Only
+the parameters named in the body change; every other parameter of the instance is left as it is. The
+metrics that consume the parameters are re-evaluated once for the whole request, so setting several
+at once costs less than a request per parameter.
+
+Every value is checked before any is applied: if one is rejected the response is a `400` and none of
+the parameters change.
+
+Endpoint:
+[PATCH /api/v2/cubes/\{dataModelId}/instances/\{instanceId}/parameters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Cubes/setMosaicParameterValues)
+
+Sample Request
+
+- Request Headers
+
+```http
+'Content-Type: application/json'
+'Accept: application/json'
+'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7'
+'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+- Request Body
+
+```json
+{
+ "parameters": [
+ { "id": "314988F06296423EB33A7361A4EB126D", "value": "100" },
+ { "id": "DB8B46BC23444186B9D05D9D1E2D71A4", "value": "800" }
+ ]
+}
+```
+
+- Curl
+
+```bash
+curl --location --request PATCH 'https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/cubes/8F4E447590CE457A983D5C3764486805/instances/3055A8906D4A8D6582A0B3BD13319E65/parameters' \
+--header 'Content-Type: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \
+--data '{
+ "parameters": [
+ { "id": "314988F06296423EB33A7361A4EB126D", "value": "100" },
+ { "id": "DB8B46BC23444186B9D05D9D1E2D71A4", "value": "800" }
+ ]
+}'
+```
+
+Sample Response
+
+- Response Body:
+
+```json
+{
+ "parameters": [
+ {
+ "id": "314988F06296423EB33A7361A4EB126D",
+ "name": "minP",
+ "value": "100"
+ },
+ {
+ "id": "DB8B46BC23444186B9D05D9D1E2D71A4",
+ "name": "maxP",
+ "value": "800"
+ }
+ ]
+}
+```
+
+- Response Code: 200 (Success: OK)
+
+## Retrieve the updated data of the instance
+
+Changing a parameter value re-evaluates the metrics that consume it, but the response of the
+parameter requests reports the parameters only. Retrieve the instance itself to read the grid data
+that the new values produced.
+
+The instance keeps its ID, so you do not create a new one. Compare the `metricValues` below with
+those returned when the instance was created: lowering `minP` from `200` to `100` and `maxP` from
+`900` to `800` changes every value the parameterized metrics produce.
+
+Endpoint: [GET /api/v2/cubes/\{dataModelId}/instances/\{instanceId}](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Cubes/getReport_1)
+
+Sample Request
+
+- Request Headers
+
+```http
+'Accept: application/json'
+'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7'
+'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+- Curl
+
+```bash
+curl --location 'https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/cubes/8F4E447590CE457A983D5C3764486805/instances/3055A8906D4A8D6582A0B3BD13319E65?limit=5' \
+--header 'Accept: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754'
+```
+
+Sample Response
+
+The `parameters` array reports the values now in effect, and `data.metricValues` holds the grid
+data produced by them.
+
+- Response Body:
+
+```json
+{
+ "name": "Airline Ticket Pricing Route Model",
+ "id": "8F4E447590CE457A983D5C3764486805",
+ "instanceId": "3055A8906D4A8D6582A0B3BD13319E65",
+ "status": 1,
+ "definition": {
+ "grid": {
+ "crossTab": false,
+ "metricsPosition": {
+ "axis": "columns",
+ "index": 0
+ },
+ "rows": [
+ {
+ "name": "From City",
+ "id": "B24BDFA9D7CB4F4FA9A8CF82FC55A59B",
+ "type": "attribute",
+ "forms": [
+ {
+ "id": "45C11FA478E745FEA08D781CEA190FE5",
+ "name": "ID",
+ "dataType": "integer",
+ "baseFormCategory": "ID",
+ "baseFormType": "number"
+ }
+ ],
+ "elements": [
+ {
+ "formValues": ["1"],
+ "id": "h1;B24BDFA9D7CB4F4FA9A8CF82FC55A59B"
+ },
+ {
+ "formValues": ["2"],
+ "id": "h2;B24BDFA9D7CB4F4FA9A8CF82FC55A59B"
+ },
+ {
+ "formValues": ["3"],
+ "id": "h3;B24BDFA9D7CB4F4FA9A8CF82FC55A59B"
+ }
+ ]
+ },
+ {
+ "name": "To City",
+ "id": "81E5474F4A314857B439BA11549500CC",
+ "type": "attribute",
+ "forms": [
+ {
+ "id": "45C11FA478E745FEA08D781CEA190FE5",
+ "name": "ID",
+ "dataType": "integer",
+ "baseFormCategory": "ID",
+ "baseFormType": "number"
+ }
+ ],
+ "elements": [
+ {
+ "formValues": ["2"],
+ "id": "h2;81E5474F4A314857B439BA11549500CC"
+ },
+ {
+ "formValues": ["3"],
+ "id": "h3;81E5474F4A314857B439BA11549500CC"
+ },
+ {
+ "formValues": ["1"],
+ "id": "h1;81E5474F4A314857B439BA11549500CC"
+ },
+ {
+ "formValues": ["6"],
+ "id": "h6;81E5474F4A314857B439BA11549500CC"
+ }
+ ]
+ }
+ ],
+ "columns": [
+ {
+ "name": "Metrics",
+ "id": "00000000000000000000000000000000",
+ "type": "templateMetrics",
+ "elements": [
+ {
+ "name": "advTicketMP",
+ "id": "FF7E9DB24B134A5A893534A466B12195",
+ "type": "metric",
+ "min": 890.0,
+ "max": 1180.0,
+ "dataType": "double",
+ "numberFormatting": {}
+ },
+ {
+ "name": "advTicketP",
+ "id": "93D34C27536A42078F867A55C4C0A077",
+ "type": "metric",
+ "min": -10.0,
+ "max": 280.0,
+ "dataType": "double",
+ "numberFormatting": {}
+ },
+ {
+ "name": "Ticket Price",
+ "id": "0D1A650A93CD4851AEA51949D4808701",
+ "type": "metric",
+ "min": 90,
+ "max": 380,
+ "dataType": "integer",
+ "numberFormatting": {
+ "category": 1,
+ "formatString": "#,##0",
+ "negativeType": 1
+ }
+ }
+ ]
+ }
+ ],
+ "sorting": {
+ "rows": [],
+ "columns": [],
+ "pageBy": []
+ },
+ "thresholds": []
+ }
+ },
+ "data": {
+ "currentPageBy": [],
+ "paging": {
+ "total": 10,
+ "current": 5,
+ "offset": 0,
+ "limit": 5
+ },
+ "headers": {
+ "rows": [
+ [0, 0],
+ [0, 1],
+ [1, 2],
+ [1, 3],
+ [2, 0]
+ ],
+ "columns": [[0, 1, 2]]
+ },
+ "metricValues": {
+ "raw": [
+ [1150.0, 250.0, 350],
+ [950.0, 50.0, 150],
+ [1180.0, 280.0, 380],
+ [1050.0, 150.0, 250],
+ [1080.0, 180.0, 280]
+ ],
+ "formatted": [
+ ["1150", "250", "350"],
+ ["950", "50", "150"],
+ ["1180", "280", "380"],
+ ["1050", "150", "250"],
+ ["1080", "180", "280"]
+ ],
+ "extras": [
+ [{}, {}, {}],
+ [{}, {}, {}],
+ [{}, {}, {}],
+ [{}, {}, {}],
+ [{}, {}, {}]
+ ]
+ }
+ },
+ "promptOrdering": [],
+ "parameters": [
+ {
+ "id": "314988F06296423EB33A7361A4EB126D",
+ "name": "minP",
+ "value": "100"
+ },
+ {
+ "id": "DB8B46BC23444186B9D05D9D1E2D71A4",
+ "name": "maxP",
+ "value": "800"
+ }
+ ]
+}
+```
+
+- Response Code: 200 (Success: OK)
+
+## Unset a parameter
+
+Send a `null` value to unset a parameter, returning it to the state it was in before it was ever
+given a value. In the response, the unset parameter has no `value` field.
+
+Endpoint:
+[PATCH /api/v2/cubes/\{dataModelId}/instances/\{instanceId}/parameters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Cubes/setMosaicParameterValues)
+
+Sample Request
+
+- Request Body
+
+```json
+{
+ "parameters": [{ "id": "314988F06296423EB33A7361A4EB126D", "value": null }]
+}
+```
+
+- Curl
+
+```bash
+curl --location --request PATCH 'https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/cubes/8F4E447590CE457A983D5C3764486805/instances/3055A8906D4A8D6582A0B3BD13319E65/parameters' \
+--header 'Content-Type: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \
+--data '{
+ "parameters": [
+ { "id": "314988F06296423EB33A7361A4EB126D", "value": null }
+ ]
+}'
+```
+
+Sample Response
+
+The unset parameter, `minP`, comes back with no `value`.
+
+- Response Body:
+
+```json
+{
+ "parameters": [
+ {
+ "id": "314988F06296423EB33A7361A4EB126D",
+ "name": "minP"
+ },
+ {
+ "id": "DB8B46BC23444186B9D05D9D1E2D71A4",
+ "name": "maxP",
+ "value": "800"
+ }
+ ]
+}
+```
+
+- Response Code: 200 (Success: OK)
+
+## Handle a rejected value
+
+A value the model will not accept is refused with a `400` that names the parameter and the problem,
+and the instance is left unchanged and still usable. Because validation runs over every value before
+any is applied, one bad value in a batch changes nothing at all.
+
+Endpoint:
+[PATCH /api/v2/cubes/\{dataModelId}/instances/\{instanceId}/parameters](https://demo.microstrategy.com/MicroStrategyLibrary/api-docs/index.html?visibility=all#/Cubes/setMosaicParameterValues)
+
+Sample Request
+
+- Request Body
+
+```json
+{
+ "parameters": [{ "id": "DB8B46BC23444186B9D05D9D1E2D71A4", "value": "abc" }]
+}
+```
+
+- Curl
+
+```bash
+curl --location --request PATCH 'https://demo.microstrategy.com/MicroStrategyLibrary/api/v2/cubes/8F4E447590CE457A983D5C3764486805/instances/3055A8906D4A8D6582A0B3BD13319E65/parameters' \
+--header 'Content-Type: application/json' \
+--header 'X-MSTR-AuthToken: knpqs112o3enhcbj4h0f5pqgu7' \
+--header 'X-MSTR-ProjectID: B7CA92F04B9FAE8D941C3E9B7E0CD754' \
+--data '{
+ "parameters": [
+ { "id": "DB8B46BC23444186B9D05D9D1E2D71A4", "value": "abc" }
+ ]
+}'
+```
+
+Sample Response
+
+- Response Body:
+
+```json
+{
+ "code": "ERR006",
+ "message": "Parameter 'maxP' expects a number, and 'abc' cannot be read as one",
+ "ticketId": "ab959235b2a649aab4dfa0c721497fa5"
+}
+```
+
+- Response Code: 400 (Bad Request)
diff --git a/docs/common-workflows/mosaic/retrieve-data-from-data-models/retrieve-data-from-data-models.md b/docs/common-workflows/mosaic/retrieve-data-from-data-models/retrieve-data-from-data-models.md
index 4961026af..72f26c102 100644
--- a/docs/common-workflows/mosaic/retrieve-data-from-data-models/retrieve-data-from-data-models.md
+++ b/docs/common-workflows/mosaic/retrieve-data-from-data-models/retrieve-data-from-data-models.md
@@ -16,4 +16,5 @@ Learn more about Strategy REST API Playground [here](/docs/getting-started/playg
Data model is a special kind of cube. You can use some cube APIs to interact with data models. The following workflows demonstrate how to retrieve data from data models using cube APIs.
- [Retrieve Data through Cube Instance](retrieve-data-through-cube-instance.md)
+- [Apply Parameters to a Data Model Instance](apply-parameters-to-a-data-model-instance.md)
- [Retrieve Data Model SQL View](retrieve-data-model-sql-view.md)
diff --git a/docs/whats-new.md b/docs/whats-new.md
index 3365a05a6..09420e3e4 100644
--- a/docs/whats-new.md
+++ b/docs/whats-new.md
@@ -4,6 +4,10 @@ sidebar_label: What's new
Description: What's New in the REST API.
---
+## Strategy (September 2026)
+
+- [Apply Parameters to a Data Model Instance](common-workflows/mosaic/retrieve-data-from-data-models/apply-parameters-to-a-data-model-instance.md)
+
## Strategy (May 2026)
- [Save a Data Model as a New Data Model](common-workflows/mosaic/manage-data-models/save-a-data-model-as-a-new-data-model.md)
@@ -126,6 +130,10 @@ Description: What's New in the REST API.
- [Bot APIs](common-workflows/analytics/use-bot-api/use-bot-api.md)
- Support [FFSQL cube](common-workflows/analytics/manage-datasets/manage-cube-objects/manage-cube-objects.md) and [FFSQL IRR](common-workflows/analytics/manage-reports/manage-incremental-refresh-report/manage-incremental-refresh-report.md).
+## 2021 Update 12
+
+- Support parameter selectors in [Manage selectors](common-workflows/analytics/manage-selectors/manage-selectors.md), [Retrieve a selector's definition](common-workflows/analytics/manage-selectors/retrieve-a-selectors-definition.md), and [Set selector type](common-workflows/analytics/manage-selectors/set-selector-type.md), including element list parameter selectors, object parameter selectors, and value parameter selectors.
+
## 2021 Update 11
- [Managing cluster startup membership configuration](common-workflows/administration/monitors/manage-an-intelligence-server-cluster.md#cluster-startup-membership)
diff --git a/sidebars.js b/sidebars.js
index 25d6aa4df..adb1be484 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -1269,6 +1269,7 @@ const sidebars = {
},
items: [
"common-workflows/mosaic/retrieve-data-from-data-models/retrieve-data-through-cube-instance",
+ "common-workflows/mosaic/retrieve-data-from-data-models/apply-parameters-to-a-data-model-instance",
"common-workflows/mosaic/retrieve-data-from-data-models/retrieve-data-model-sql-view",
],
},