Reporting is a resource for aggregating iTwin data to build custom dashboards and integrate iTwin data with your business applications.

- Create digitial twin based reports which can be consumed through business intelligence applications such as Power BI.
- Leverage the OData feed Data Access to generate reports by combining data from multiple data streams in the digital twin.

insights

Reporting & Insights

---

Lists all OData Entities for a Report. This endpoint can be used as an OData feed in applications like Excel or Power BI.

### Notes

This is an OData v4 compliant endpoint.

This endpoint should only be accessed using OData compliant libraries and tools such as Power BI.

Use of these endpoints directly is not prohibited, however we recommend understanding the [OData protocols and conventions](https://www.odata.org/documentation/) first.

### Authentication

Requires `Authorization` header with one of schemes:

- Valid [API Key](/apis/insights/api-keys) used as the password in Basic auth.
- Valid Bearer token for scope `insights:read`.

### Authorization

User must have `insights_view` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


odata

reportId

OAuth access token with scope `insights:read`

Authorization

Setting to `application/vnd.bentley.itwin-platform.v1+json` is recommended.

Accept

Retrieved OData feed and metadata for a given Report successfully. (NOTE: the URLs in the response are relative URLs compliant with OData v4 that are used to access the data within each Entity. Usage of these relative URLs is documented under the 'OData Entity' endpoint.)

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

---

Lists the raw table data for a Report Entity. 

### Notes

This is an OData v4 compliant endpoint.

This endpoint should only be accessed using OData compliant libraries and tools such as Power BI.

Use of these endpoints directly is not prohibited, however we recommend understanding the [OData protocols and conventions](https://www.odata.org/documentation/) first.

### Authentication

Requires `Authorization` header with one of schemes:

- Valid [API Key](/apis/insights/api-keys) used as the password in Basic auth.
- Valid Bearer token for scope `insights:read`.

### Authorization

User must have `insights_view` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


odata-entity

NOTE: These parameters are not meant to be set manually. Instead use the URLs generated by the OData endpoint directly.

region

manifestId

entityType

Retrieved specified OData Entity successfully.

---

Lists schemas for all Entities tied to a Report.

### Notes

This is an OData v4 compliant endpoint.

This endpoint should only be accessed using OData compliant libraries and tools such as Power BI.

Use of these endpoints directly is not prohibited, however we recommend understanding the [OData protocols and conventions](https://www.odata.org/documentation/) first.

### Authentication

Requires `Authorization` header with one of schemes:

- Valid [API Key](/apis/insights/api-keys) used as the password in Basic auth.
- Valid Bearer token for scope `insights:read`.

### Authorization

User must have `insights_view` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


odata-metadata

Retrieved Report OData metadata successfully.

---

Gets Logs of an Extraction Run.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


get-extraction-logs

jobId

Optional max items to be sent in response.

$top

Optional token to retrieve next page in paginated response.

$continuationToken

Specified Extraction Logs were not found.

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

---

Gets the Status of an Extraction Run.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-extraction-status

Retrieved status of Extraction Run successfully.

Specified ExtractionStatus was not found.

get-extraction-status-deprecated

Globally Unique Identifier of the target iModel.

imodelId

---

Manually run Extraction of data from an iModel. Latest Named Version is used for Extraction.

For the iModel data source, data must be Extracted first before it can be used in your Reports.

### Notes

iModel data Extraction is executed automatically after new Named Version is created. Do not call this API on scheduled basis or after making changes to an iModel.

Only call this API after creating or changing an iModel Mapping.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


run-extraction

OAuth access token with scope `insights:modify`

The user has insufficient permissions for the requested operation.

---

Copies a Mapping and all its Groups, GroupProperties, CalculatedProperties, and CustomCalculations to a target iModel.

The `mappingName` request body property is optional. If the `mappingName` is not provided the new Mapping will have the same name as the source Mapping but with the `_Copy` appendix. If the `mappingName` is provided the new Mapping will have the provided name.

The `mappingName` property becomes mandatory if the source Mapping has 124 or more characters in its name.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


copy-mapping

mappingId

---

Creates a CalculatedProperty for a Group. Each CalculatedProperty defines a property or 'column' which is calculated for each element that is returned by the Group's query.

### Calculation Types

Calculation types that start with `BoundingBox` use element aligned bounding boxes. They can be used for approximations of geometric element dimensions when there are no available properties that would have exact dimensions. Some errors may occur due to bounding boxes not being a perfect fit for the surrounded element.

List of all available calculation types:

- `Length` - calculation of a linear element length or a perimeter of a geometric element that does not have a volume. For elements that have a volume use BoundingBox calculations to approximate the length.
- `Area` - calculation of a geometric element's surface area.
- `Volume` - calculation of a geometric element's volume.
- `BoundingBoxLongestEdgeLength` - calculation that gives the longest edge length of an element aligned bounding box.
- `BoundingBoxIntermediateEdgeLength` - calculation that gives the edge length that is not the longest nor the shortest of an element aligned bounding box.
- `BoundingBoxShortestEdgeLength` - calculation that gives the shortest edge length of an element aligned bounding box.
- `BoundingBoxDiagonalLength` - calculation that gives the distance between 2 opposite corners of the element aligned bounding box.
- `BoundingBoxLongestFaceDiagonalLength` - calculation that gives the longest distance between 2 opposite corners of a face on the element aligned bounding box.
- `BoundingBoxIntermediateFaceDiagonalLength` - calculation that gives the distance between 2 opposite corners of a face on the element aligned bounding box that is not the longest nor the shortest.
- `BoundingBoxShortestFaceDiagonalLength` - calculation that gives the shortest distance between 2 opposite corners of a face on the element aligned bounding box.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


create-calculatedproperty

Id of the Group for which to create a new CalculatedProperty.

groupId

Created a new CalculatedProperty successfully.

Specified CalculatedProperty was not found.

CalculatedProperty with the same name already exists within the Group.

---

Creates a CustomCalculation for a Group. Each CustomCalculation defines a column in the output data which is filled with values calculated using the given formula for each element that is returned by the Group's query.

### CustomCalculations

CustomCalculation is a type of Group property which contains a formula. CustomCalculation defines a column in the output data that gets filled with the formula evaluation result. The formula is evaluated for each row of the Group's query result during each extraction.

The formula supports using other columns (GroupProperty, CalculatedProperty or CustomCalculation entities) as variables. Recursive formulas are not supported, i.e., formula containing a variable `X` is not supported inside a CustomCalculation with a `propertyName` equal to `X`.

Supported data types:

- Number - describes a real number. When converted to a boolean value in logical operators `0` becomes `false` and all other values become `true`
- Boolean - describes a logical value which is either true or false. When converted to a number in certain operators `true` becomes `1` and `false` becomes `0`
- String - describes text. When converted to a boolean value in logical operators an empty string becomes `false` and all other strings become `true`

All of the supported data types can have no value which means that the value is `null`. Some operations support `null` values but those which do not will return `null` as the result.

Supported operators:

| Symbol | Name | Precedence | Associativity | Operand Types | Can receive null | Result |
|--|--|--|--|--|--|--|
| Unary `-` | Unary negation | 9 | Right | Numbers and booleans | No | Number |
| `!` | Logical not | 9 | Right | All data types | No | Boolean |
| `**` | Exponentiation | 8 | Right | Numbers and booleans | No | Number |
| `*` | Multiplication | 7 | Left | Numbers and booleans | No | Number |
| `/` | Division | 7 | Left | Numbers and booleans | No | Number |
| `%` | Remainder | 7 | Left | Numbers and booleans | No | Number |
| `+` | Addition | 6 | Left | All data types | No | Number or string if one of the operands is a string |
| Binary `-` | Subtraction | 6 | Left | Numbers and booleans | No | Number |
| `<` | Less than | 5 | Left | All data types | No | Boolean |
| `<=` | Less than or equal | 5 | Left | All data types | No | Boolean |
| `>` | Greater than | 5 | Left | All data types | No | Boolean |
| `>=` | Greater than or equal | 5 | Left | All data types | No | Boolean |
| `==` | Equality | 4 | Left | All data types | Yes | Boolean |
| `!=` | Inequality | 4 | Left | All data types | Yes | Boolean |
| `&&` | Logical and | 3 | Left | All data types | No | Boolean |
| `\|\|` | Logical or | 2 | Left | All data types | No | Boolean |

Parenthesis `(` and `)` can be used to change the precedence of operations. Variables, constants, and functions have a precedence of 1 and left associativity.

Supported constants:

- `E` - Euler's constant and the base of natural logarithms (approx. 2.718)
- `LN2` - natural logarithm of 2 (approx. 0.693)
- `LN10` - natural logarithm of 10 (approx. 2.303)
- `LOG2E` - base-2 logarithm of `E` (approx. 1.443)
- `PI` - ratio of a circle's circumference to its diameter (approx. 3.14159)
- `SQRT1_2` - square root of ½ (approx. 0.707)
- `SQRT2` - square root of 2 (approx. 1.414)

Supported numeric constant formats:

- Decimal, e.g., `123` or `1.123`
- Binary (base 2), e.g., `0b1010`
- Octal (base 8), e.g., `0o1234567`
- Hexadecimal (base 16), e.g., `0x123af`
- Scientific notation, e.g., `1.123e+3`

Supported string literal formats:

- Single quotation marks, e.g., `'Column'`
- Double quotation marks, e.g., `"Column"`
- Backticks, e.g., `` `Column` ``

Supported boolean formats:

- True, e.g., `true`
- False, e.g., `false`

Supported null format:

- Null, e.g., `null`

An escape character `\` can be used to escape special characters in string literals. Supported escape sequences:

- `\'` - single quotation mark
- `\"` - double quotation mark
- `` \` `` - backtick
- `\\` - backslash
- `\n` - newline character
- `\t` - tab character

If an unsupported escape sequence is found, then the escape character is dropped, e.g., `\d` becomes `d`.

Supported numerical functions:

- `abs(x)` - returns the absolute value of `x`
- `acos(x)` - returns the arccosine of `x`
- `acosh(x)` - returns the hyperbolic arccosine of `x`
- `asin(x)` - returns the arcsine of `x`
- `asinh(x)` - returns the hyperbolic arcsine of `x`
- `atan(x)` - returns the arctangent of `x`
- `atanh(x)` - returns the hyperbolic arctangent of `x`
- `atan2(y, x)` - returns the arctangent of the quotient of `y` divided by `x`
- `cbrt(x)` - returns the cube root of `x`
- `ceil(x)` - returns the smallest integer greater than or equal to `x`
- `clz32(x)` - returns the number of leading zero bits of the 32-bit integer `x`
- `cos(x)` - returns the cosine of `x`
- `cosh(x)` - returns the hyperbolic cosine of `x`
- `exp(x)` - returns `E ** x` or `pow(E, x)`, where `x` is the argument, and `E` is Euler's constant (2.718…, the base of the natural logarithm)
- `expm1(x)` - returns subtracting 1 from `exp(x)`
- `floor(x)` - returns the largest integer less than or equal to `x`
- `fround(x)` - returns the nearest single precision float representation of `x`
- `hypot(x, y[, z[, …]])` - returns the square root of the sum of squares of its arguments
- `imul(x, y)` - returns the result of the 32-bit integer multiplication of `x` and `y`
- `log(x)` - returns the natural logarithm of `x`
- `log1p(x)` - returns the natural logarithm of `1 + x`
- `log10(x)` - returns the base-10 logarithm of `x`
- `log2(x)` - returns the base-2 logarithm of `x`
- `max(x, y[, z[, …]])` - returns the largest of 2 or more numbers
- `min(x, y[, z[, …]])` - returns the smallest of 2 or more numbers
- `pow(x, y)` - returns base `x` to the exponent power `y` (i.e., `x**y`)
- `random()` - returns a pseudo-random number between 0 and 1. The value only changes between different output tables. All rows within a single output table get the same value
- `round(x)` - returns the value of the number `x` rounded to the nearest integer
- `sign(x)` - returns the sign of the `x`, indicating whether `x` is positive (`1`), negative (`-1`), or zero (`0`)
- `sin(x)` - returns the sine of `x`
- `sinh(x)` - returns the hyperbolic sine of `x`
- `sqrt(x)` - returns the positive square root of `x`
- `tan(x)` - returns the tangent of `x`
- `tanh(x)` - returns the hyperbolic tangent of `x`
- `trunc(x)` - returns the integer portion of `x`, removing any fractional digits

Supported string functions:

- `charat(str, index)` - returns exactly one character at the specified index. Accepts negative integers, which count back from the last string character
- `concat(str , ...strN)` - combines the text of two (or more) strings and returns a new string
- `padend(str, targetLength [, padString])` - pads the given string from the end with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `padstart(str, targetLength [, padString])` - pads the given string from the start with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `substring(str, beginIndex [, endIndex])` - returns a new string containing characters of `str` from (or between) the specified index (or indices)
- `tolowercase(str)` - returns the `str` value converted to lowercase
- `touppercase(str)` - returns the `str` value converted to uppercase
- `trim(str)` - trims whitespace from the beginning and end of `str`
- `trimstart(str)` - trims whitespace from beginning of `str`
- `trimend(str)` - trims whitespace from end of `str`

Supported conditional functions:

- `if(cond, expr_true, expr_false)` - returns `expr_true` if `cond` is `true` else it returns `expr_false`. `expr_true` and `expr_false` must be of the same type. `expr_true` and `expr_false` can be `null`
- `ifnull(var, expr)` - returns `expr` if `var` is `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifnotnull(var, expr)` - returns `expr` if `var` is not `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifempty(str, expr)` - returns `expr` if `str` is empty else it returns `str`. `str` and `expr` must be strings
- `ifnotempty(str, expr)` - returns `expr` if `str` is not empty else it returns `str`. `str` and `expr` must be strings
- `ifnullorempty(str, expr)` - returns `expr` if `str` is null or empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorempty(str, expr)` - returns `expr` if `str` is not null and not empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnullorwhitespace(str, expr)` - returns `expr` if `str` is null or empty or only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorwhitespace(str, expr)` - returns `expr` if `str` is not null and not empty and not only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`

Examples of supported formulas:

- `min(A * B, B * C, A * C)` - if `A`, `B`, and `C` are 3 different lengths of box edges, then this formula will result in the smallest side surface area of that box
- `min * max` - formula does not have parenthesis after function names, so the `min` and `max` operands are treated as variables (other columns), not as functions. If the Group has columns `min` and `max`, and their values are `2` and `5`, then the result of this formula is `10` for that row
- `2 ** 3` - 2 raised to the power of 3. Result will be 8. This can also be written as `pow(2, 3)`
- `min(cos(X), sin(X))` - function nesting is supported
- `A * (B + C)` - `A` multiplied by the sum of `B` and `C`
- `A * B + C` - same as `(A * B) + C`
- `padend(concat(A, '\\', touppercase(substring(B, 4))), C, D)` - the result of `concat`, which concatenates variable `A`, string literal `\` and `uppercase` `substring` of variable `B` from index `4`, is padded in the end with the target length of `C` with a pad string of variable `D`
- `charat(trim(A), B)` - gets the character of a trimmed string variable `A` that is at index `B`
- `if(A > B, A, B)` - if `A` is greater than `B` then the result is `A` else it is `B`
- `ifnullorempty(A, 'B = ') + B` - if variable `A` is null or empty then the result of `ifnullorempty` function is the string literal `B = ` else it is variable `A`. Then the final formula result is the addition of the result of `ifnullorempty` function and variable `B`
- `if(A != null && B != null, A + B, 0)` - if `A` is not null and `B` is not null then the result is the addition of `A` and `B` else it is `0`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


create-customcalculation

Id of the Group for which to create a new CustomCalculation.

Created a new CustomCalculation successfully.

Specified CustomCalculation was not found.

CustomCalculation with the same name already exists within the Group.

---

Creates a Group for an iModel data source Mapping. A Group is a collection of design elements from an iModel represented by an [ECSQL](https://www.itwinjs.org/learning/ecsql/) query and defines one table in the output data of a report.

### Group Query

The `query` parameter of a Group supports ECSql and ECClassIds.

If a valid ECSql query is given and the selected class is `bis.Element`, or if it is a descendant of the class `bis.Element`, the only required column is `ECInstanceId`.

- `SELECT * FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT * FROM Building.Beam` is a valid query
- `SELECT ECInstanceId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId FROM Building.Beam` is valid
- `SELECT ECClassId FROM bis.Element` is _not_ a valid query because ECInstanceId column is missing
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECClassId FROM Building.Beam` is _not_ valid because ECInstanceId column is missing
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.ECInstanceId FROM bis.Element E JOIN Building.BeamAspect A ON A.Element.id = E.ECInstanceId` is _not_ valid because the selected `ECInstanceId` is of the aspect, not the element
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id FROM Building.BeamAspect` is _not_ valid because the selected column's name is not `ECInstanceId`
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases when providing an ECSql query it is required to select `ECInstanceId`, `ECClassId`, and all other columns that you are planning to use for mapping. If only `ECInstanceId` and `ECClassId` are selected and other columns are used for mapping, those columns will be filled with `null` values. If either `ECInstanceId` or `ECClassId` column is not selected, the query will not produce any output.

If the `query` parameter does not contain a valid ECSql query, then it must be equal to `bis.Element`, `bis.ElementAspect`, or any of their descendants.

The ECClassId format `{schemaName}:{schemaItemName}` where `schemaName` does not contain a 3-part version number is supported.

The ECClassId format `{schemaName}.{schemaItemName}` is supported.

The ECClassId format `{schemaAlias}:{schemaItemName}` where `schemaAlias` is the alias of a `schemaName` is supported.

The ECClassId format `{schemaFullName}:{schemaItemName}` where `schemaFullName` contains a 3-part version number is _not_ supported.

When the given ECClassId is equal to `bis.Element` or is one of its descendants, then all elements with the ECClassId will be selected.

When the given ECClassId is equal to `bis.ElementAspect` or is one of its descendants, then all elements that have such aspect will be selected.

When the given ECClassId is none of the above, the query will not produce any output.

- If a class `Building.Beam` does not have any subclasses and the `query` parameter is set to `Building.Beam`, then all elements with ECClassIds of `Building.Beam` will be selected
- If there is a class `Building.StructuralMember` which has 2 subclasses `Building.Beam` and `Building.Column`, and the `query` parameter is set to `Building.StructuralMember`, then all elements with ECClassIds of `Building.StructuralMember`, `Building.Beam`, and `Building.Column` will be selected
- If a class `Building.BeamAspect` inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.BeamAspect`, then all elements that have a `Building.BeamAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId
- If there is class `Building.StructuralMemberAspect` which has 2 subclasses `Building.BeamAspect` and `Building.ColumnAspect`, the `Building.StructuralMemberAspect` class inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.StructuralMemberAspect`, then all elements that have `Building.StructuralMemberAspect`, `Building.BeamAspect`, or `Building.ColumnAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId

If different queries are needed for a single output table, then create multiple Groups with those different queries but with the same name for each Group. That will cause results of all these queries to be concatenated into a single output table. The output table will have column list equal to a union of all GroupProperties of Groups with the same name.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


create-group

Id of the Mapping for which to create a new Group.

---

Creates a GroupProperty for a Group. Each GroupProperty defines a column of mapped data.

### Mapping ECProperties

GroupProperties define mappings from ECProperties on an iModel to columns. They allow mapping the queried, element, element aspect, or related element properties.

Content of the columns depend on the `ecProperties` field. The `ecProperties` field is a prioritized array which contains `ECProperty` entities. The closer the `ECProperty` is to the array's start, the higher the priority. The priority of `ECProperty` can be changed by reordering the `ecProperties` array. Reading of the `ecProperties` array stops when a valid value is found. For example, if the `ecProperties` array contains two entries and the first entry results in a null or undefined value, it will take the second entry. The value can be undefined if the given ECProperty does not exist. The result column will be filled with a null value if no valid value was found.

Evaluating `ecProperties` is prioritized by:

1. Queried properties
2. Element properties
3. Element aspect properties

Having queried properties as the highest priority allows for constant or complex values to be added to a mapping.

`ECProperty` lookup is defined by three values - `ECSchemaName`, `ECClassName`, and `ECPropertyName`.

`ECSchemaName` and `ECClassName` are used together to create a ECClassId which is the ECClassId of the current row when selecting a property. If the ECClassId of a selected row does not match the `ECSchemaName` and `ECClassName` pair, the value for this `ECProperty` is considered undefined. If the formed ECClassId is of an element aspect, the current selected row is an element and there is only one instance of that element aspect related to the element, the property lookup is done on the element aspect.

`ECSchemaName` and `ECClassName` are case-insensitive.

`ECSchemaName` and `ECClassName` can be set to a wildcard value `*`.

- If the value of `ECSchemaName` is `*` and the value of `ECClassName` is `Beam`, then it will match any `Beam` class from any schema (e.g. `Building.Beam`, `Structural.Beam`, etc.)
- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `*`, then it will match any class from the schema `Building` (e.g. `Building.Beam`, `Building.CurtainWall`, etc.)
- If values of `ECSchemaName` and `ECClassName` are `*`, then it will match any ECClassId (e.g. `Building.Beam`, `Structural.Column`, etc.)
- If either value of `ECSchemaName` or `ECClassName` are `*`, then no element aspect lookup is done

Class inheritance is checked if there is no wildcard value.

- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `StructuralMember`, then it will match any ECClassId which inherits `Building.StructuralMember` (e.g. `Building.Beam` which inherits `Building.StructuralMember`, `Building.Column` which inherits `Building.StructuralMember`, etc)
- If `ECSchemaName` or `ECClassName` is a wildcard, then inheritance will not be checked

Set `ECPropertyName` to a property name that you want to select. The value of `ECPropertyName` can also be a path defining how to find a property. The path segments must be separated by a period (`.`). The path can contain the names of:

- A navigation property
- A struct property
- A string property that happens to contain a string representation of a json object
- A property inside the selected json

Names of properties are not case sensitive. If json object does not have duplicate property names which only differ in letter casing, then those json properties are not case sensitive. We recommend treating json properties as case sensitive.

- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category` or `category`, then the whole value `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` will be selected
- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category.id`, then only the `id` value `0x2000000000b` will be selected
- If `Category` property is a navigation property and it points to a row that has a property `CodeValue` that we want to select, the `ECPropertyName` should be set to `Category.CodeValue`
- If `Model` property is a navigation property and it points to a row that has a property `JsonProperties` with a value `{"formatter":{"mastUnit":{"label":"m"}}}` and we want to select the master unit label, the `ECPropertyName` should be set to `Model.JsonProperties.formatter.mastUnit.label`. The result will be `m`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


create-groupproperty

Id of the Group for which to create a new GroupProperty.

Created a new GroupProperty successfully.

GroupProperty with the same name already exists within the Group.

---

Creates a Mapping for an iModel. Each Mapping represents a collection of tables (Groups) of data that can be consumed in a Report.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


create-mapping

Id of the iModel for which to create a new Mapping.

---

Deletes a CalculatedProperty from a Group.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


delete-calculatedproperty

Id of the CalculatedProperty to be deleted.

propertyId

Deleted a CalculatedProperty successfully.

---

Deletes a CustomCalculation from a Group.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


delete-customcalculation

Id of the CustomCalculation to be deleted.

customCalculationId

Deleted a CustomCalculation successfully.

---

Deletes a Group for a Mapping.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


delete-group

---

Deletes a GroupProperty from a Group.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


delete-groupproperty

---

Deletes a Mapping for an iModel.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


delete-mapping

---

Gets all CalculatedProperties for a Group.

### Calculation Types

Calculation types that start with `BoundingBox` use element aligned bounding boxes. They can be used for approximations of geometric element dimensions when there are no available properties that would have exact dimensions. Some errors may occur due to bounding boxes not being a perfect fit for the surrounded element.

List of all available calculation types:

- `Length` - calculation of a linear element length or a perimeter of a geometric element that does not have a volume. For elements that have a volume use BoundingBox calculations to approximate the length.
- `Area` - calculation of a geometric element's surface area.
- `Volume` - calculation of a geometric element's volume.
- `BoundingBoxLongestEdgeLength` - calculation that gives the longest edge length of an element aligned bounding box.
- `BoundingBoxIntermediateEdgeLength` - calculation that gives the edge length that is not the longest nor the shortest of an element aligned bounding box.
- `BoundingBoxShortestEdgeLength` - calculation that gives the shortest edge length of an element aligned bounding box.
- `BoundingBoxDiagonalLength` - calculation that gives the distance between 2 opposite corners of the element aligned bounding box.
- `BoundingBoxLongestFaceDiagonalLength` - calculation that gives the longest distance between 2 opposite corners of a face on the element aligned bounding box.
- `BoundingBoxIntermediateFaceDiagonalLength` - calculation that gives the distance between 2 opposite corners of a face on the element aligned bounding box that is not the longest nor the shortest.
- `BoundingBoxShortestFaceDiagonalLength` - calculation that gives the shortest distance between 2 opposite corners of a face on the element aligned bounding box.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-calculatedproperties

Retrieved CalculatedProperties successfully.

---

Gets a CalculatedProperty for a Group.

### Calculation Types

Calculation types that start with `BoundingBox` use element aligned bounding boxes. They can be used for approximations of geometric element dimensions when there are no available properties that would have exact dimensions. Some errors may occur due to bounding boxes not being a perfect fit for the surrounded element.

List of all available calculation types:

- `Length` - calculation of a linear element length or a perimeter of a geometric element that does not have a volume. For elements that have a volume use BoundingBox calculations to approximate the length.
- `Area` - calculation of a geometric element's surface area.
- `Volume` - calculation of a geometric element's volume.
- `BoundingBoxLongestEdgeLength` - calculation that gives the longest edge length of an element aligned bounding box.
- `BoundingBoxIntermediateEdgeLength` - calculation that gives the edge length that is not the longest nor the shortest of an element aligned bounding box.
- `BoundingBoxShortestEdgeLength` - calculation that gives the shortest edge length of an element aligned bounding box.
- `BoundingBoxDiagonalLength` - calculation that gives the distance between 2 opposite corners of the element aligned bounding box.
- `BoundingBoxLongestFaceDiagonalLength` - calculation that gives the longest distance between 2 opposite corners of a face on the element aligned bounding box.
- `BoundingBoxIntermediateFaceDiagonalLength` - calculation that gives the distance between 2 opposite corners of a face on the element aligned bounding box that is not the longest nor the shortest.
- `BoundingBoxShortestFaceDiagonalLength` - calculation that gives the shortest distance between 2 opposite corners of a face on the element aligned bounding box.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-calculatedproperty

Retrieved a CalculatedProperty successfully.

---

Gets a CustomCalculation for a Group.

### CustomCalculations

CustomCalculation is a type of Group property which contains a formula. CustomCalculation defines a column in the output data that gets filled with the formula evaluation result. The formula is evaluated for each row of the Group's query result during each extraction.

The formula supports using other columns (GroupProperty, CalculatedProperty or CustomCalculation entities) as variables. Recursive formulas are not supported, i.e., formula containing a variable `X` is not supported inside a CustomCalculation with a `propertyName` equal to `X`.

Supported data types:

- Number - describes a real number. When converted to a boolean value in logical operators `0` becomes `false` and all other values become `true`
- Boolean - describes a logical value which is either true or false. When converted to a number in certain operators `true` becomes `1` and `false` becomes `0`
- String - describes text. When converted to a boolean value in logical operators an empty string becomes `false` and all other strings become `true`

All of the supported data types can have no value which means that the value is `null`. Some operations support `null` values but those which do not will return `null` as the result.

Supported operators:

| Symbol | Name | Precedence | Associativity | Operand Types | Can receive null | Result |
|--|--|--|--|--|--|--|
| Unary `-` | Unary negation | 9 | Right | Numbers and booleans | No | Number |
| `!` | Logical not | 9 | Right | All data types | No | Boolean |
| `**` | Exponentiation | 8 | Right | Numbers and booleans | No | Number |
| `*` | Multiplication | 7 | Left | Numbers and booleans | No | Number |
| `/` | Division | 7 | Left | Numbers and booleans | No | Number |
| `%` | Remainder | 7 | Left | Numbers and booleans | No | Number |
| `+` | Addition | 6 | Left | All data types | No | Number or string if one of the operands is a string |
| Binary `-` | Subtraction | 6 | Left | Numbers and booleans | No | Number |
| `<` | Less than | 5 | Left | All data types | No | Boolean |
| `<=` | Less than or equal | 5 | Left | All data types | No | Boolean |
| `>` | Greater than | 5 | Left | All data types | No | Boolean |
| `>=` | Greater than or equal | 5 | Left | All data types | No | Boolean |
| `==` | Equality | 4 | Left | All data types | Yes | Boolean |
| `!=` | Inequality | 4 | Left | All data types | Yes | Boolean |
| `&&` | Logical and | 3 | Left | All data types | No | Boolean |
| `\|\|` | Logical or | 2 | Left | All data types | No | Boolean |

Parenthesis `(` and `)` can be used to change the precedence of operations. Variables, constants, and functions have a precedence of 1 and left associativity.

Supported constants:

- `E` - Euler's constant and the base of natural logarithms (approx. 2.718)
- `LN2` - natural logarithm of 2 (approx. 0.693)
- `LN10` - natural logarithm of 10 (approx. 2.303)
- `LOG2E` - base-2 logarithm of `E` (approx. 1.443)
- `PI` - ratio of a circle's circumference to its diameter (approx. 3.14159)
- `SQRT1_2` - square root of ½ (approx. 0.707)
- `SQRT2` - square root of 2 (approx. 1.414)

Supported numeric constant formats:

- Decimal, e.g., `123` or `1.123`
- Binary (base 2), e.g., `0b1010`
- Octal (base 8), e.g., `0o1234567`
- Hexadecimal (base 16), e.g., `0x123af`
- Scientific notation, e.g., `1.123e+3`

Supported string literal formats:

- Single quotation marks, e.g., `'Column'`
- Double quotation marks, e.g., `"Column"`
- Backticks, e.g., `` `Column` ``

Supported boolean formats:

- True, e.g., `true`
- False, e.g., `false`

Supported null format:

- Null, e.g., `null`

An escape character `\` can be used to escape special characters in string literals. Supported escape sequences:

- `\'` - single quotation mark
- `\"` - double quotation mark
- `` \` `` - backtick
- `\\` - backslash
- `\n` - newline character
- `\t` - tab character

If an unsupported escape sequence is found, then the escape character is dropped, e.g., `\d` becomes `d`.

Supported numerical functions:

- `abs(x)` - returns the absolute value of `x`
- `acos(x)` - returns the arccosine of `x`
- `acosh(x)` - returns the hyperbolic arccosine of `x`
- `asin(x)` - returns the arcsine of `x`
- `asinh(x)` - returns the hyperbolic arcsine of `x`
- `atan(x)` - returns the arctangent of `x`
- `atanh(x)` - returns the hyperbolic arctangent of `x`
- `atan2(y, x)` - returns the arctangent of the quotient of `y` divided by `x`
- `cbrt(x)` - returns the cube root of `x`
- `ceil(x)` - returns the smallest integer greater than or equal to `x`
- `clz32(x)` - returns the number of leading zero bits of the 32-bit integer `x`
- `cos(x)` - returns the cosine of `x`
- `cosh(x)` - returns the hyperbolic cosine of `x`
- `exp(x)` - returns `E ** x` or `pow(E, x)`, where `x` is the argument, and `E` is Euler's constant (2.718…, the base of the natural logarithm)
- `expm1(x)` - returns subtracting 1 from `exp(x)`
- `floor(x)` - returns the largest integer less than or equal to `x`
- `fround(x)` - returns the nearest single precision float representation of `x`
- `hypot(x, y[, z[, …]])` - returns the square root of the sum of squares of its arguments
- `imul(x, y)` - returns the result of the 32-bit integer multiplication of `x` and `y`
- `log(x)` - returns the natural logarithm of `x`
- `log1p(x)` - returns the natural logarithm of `1 + x`
- `log10(x)` - returns the base-10 logarithm of `x`
- `log2(x)` - returns the base-2 logarithm of `x`
- `max(x, y[, z[, …]])` - returns the largest of 2 or more numbers
- `min(x, y[, z[, …]])` - returns the smallest of 2 or more numbers
- `pow(x, y)` - returns base `x` to the exponent power `y` (i.e., `x**y`)
- `random()` - returns a pseudo-random number between 0 and 1. The value only changes between different output tables. All rows within a single output table get the same value
- `round(x)` - returns the value of the number `x` rounded to the nearest integer
- `sign(x)` - returns the sign of the `x`, indicating whether `x` is positive (`1`), negative (`-1`), or zero (`0`)
- `sin(x)` - returns the sine of `x`
- `sinh(x)` - returns the hyperbolic sine of `x`
- `sqrt(x)` - returns the positive square root of `x`
- `tan(x)` - returns the tangent of `x`
- `tanh(x)` - returns the hyperbolic tangent of `x`
- `trunc(x)` - returns the integer portion of `x`, removing any fractional digits

Supported string functions:

- `charat(str, index)` - returns exactly one character at the specified index. Accepts negative integers, which count back from the last string character
- `concat(str , ...strN)` - combines the text of two (or more) strings and returns a new string
- `padend(str, targetLength [, padString])` - pads the given string from the end with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `padstart(str, targetLength [, padString])` - pads the given string from the start with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `substring(str, beginIndex [, endIndex])` - returns a new string containing characters of `str` from (or between) the specified index (or indices)
- `tolowercase(str)` - returns the `str` value converted to lowercase
- `touppercase(str)` - returns the `str` value converted to uppercase
- `trim(str)` - trims whitespace from the beginning and end of `str`
- `trimstart(str)` - trims whitespace from beginning of `str`
- `trimend(str)` - trims whitespace from end of `str`

Supported conditional functions:

- `if(cond, expr_true, expr_false)` - returns `expr_true` if `cond` is `true` else it returns `expr_false`. `expr_true` and `expr_false` must be of the same type. `expr_true` and `expr_false` can be `null`
- `ifnull(var, expr)` - returns `expr` if `var` is `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifnotnull(var, expr)` - returns `expr` if `var` is not `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifempty(str, expr)` - returns `expr` if `str` is empty else it returns `str`. `str` and `expr` must be strings
- `ifnotempty(str, expr)` - returns `expr` if `str` is not empty else it returns `str`. `str` and `expr` must be strings
- `ifnullorempty(str, expr)` - returns `expr` if `str` is null or empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorempty(str, expr)` - returns `expr` if `str` is not null and not empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnullorwhitespace(str, expr)` - returns `expr` if `str` is null or empty or only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorwhitespace(str, expr)` - returns `expr` if `str` is not null and not empty and not only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`

Examples of supported formulas:

- `min(A * B, B * C, A * C)` - if `A`, `B`, and `C` are 3 different lengths of box edges, then this formula will result in the smallest side surface area of that box
- `min * max` - formula does not have parenthesis after function names, so the `min` and `max` operands are treated as variables (other columns), not as functions. If the Group has columns `min` and `max`, and their values are `2` and `5`, then the result of this formula is `10` for that row
- `2 ** 3` - 2 raised to the power of 3. Result will be 8. This can also be written as `pow(2, 3)`
- `min(cos(X), sin(X))` - function nesting is supported
- `A * (B + C)` - `A` multiplied by the sum of `B` and `C`
- `A * B + C` - same as `(A * B) + C`
- `padend(concat(A, '\\', touppercase(substring(B, 4))), C, D)` - the result of `concat`, which concatenates variable `A`, string literal `\` and `uppercase` `substring` of variable `B` from index `4`, is padded in the end with the target length of `C` with a pad string of variable `D`
- `charat(trim(A), B)` - gets the character of a trimmed string variable `A` that is at index `B`
- `if(A > B, A, B)` - if `A` is greater than `B` then the result is `A` else it is `B`
- `ifnullorempty(A, 'B = ') + B` - if variable `A` is null or empty then the result of `ifnullorempty` function is the string literal `B = ` else it is variable `A`. Then the final formula result is the addition of the result of `ifnullorempty` function and variable `B`
- `if(A != null && B != null, A + B, 0)` - if `A` is not null and `B` is not null then the result is the addition of `A` and `B` else it is `0`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-customcalculation

Retrieved a CustomCalculation successfully.

---

Gets all CustomCalculations for a Group.

### CustomCalculations

CustomCalculation is a type of Group property which contains a formula. CustomCalculation defines a column in the output data that gets filled with the formula evaluation result. The formula is evaluated for each row of the Group's query result during each extraction.

The formula supports using other columns (GroupProperty, CalculatedProperty or CustomCalculation entities) as variables. Recursive formulas are not supported, i.e., formula containing a variable `X` is not supported inside a CustomCalculation with a `propertyName` equal to `X`.

Supported data types:

- Number - describes a real number. When converted to a boolean value in logical operators `0` becomes `false` and all other values become `true`
- Boolean - describes a logical value which is either true or false. When converted to a number in certain operators `true` becomes `1` and `false` becomes `0`
- String - describes text. When converted to a boolean value in logical operators an empty string becomes `false` and all other strings become `true`

All of the supported data types can have no value which means that the value is `null`. Some operations support `null` values but those which do not will return `null` as the result.

Supported operators:

| Symbol | Name | Precedence | Associativity | Operand Types | Can receive null | Result |
|--|--|--|--|--|--|--|
| Unary `-` | Unary negation | 9 | Right | Numbers and booleans | No | Number |
| `!` | Logical not | 9 | Right | All data types | No | Boolean |
| `**` | Exponentiation | 8 | Right | Numbers and booleans | No | Number |
| `*` | Multiplication | 7 | Left | Numbers and booleans | No | Number |
| `/` | Division | 7 | Left | Numbers and booleans | No | Number |
| `%` | Remainder | 7 | Left | Numbers and booleans | No | Number |
| `+` | Addition | 6 | Left | All data types | No | Number or string if one of the operands is a string |
| Binary `-` | Subtraction | 6 | Left | Numbers and booleans | No | Number |
| `<` | Less than | 5 | Left | All data types | No | Boolean |
| `<=` | Less than or equal | 5 | Left | All data types | No | Boolean |
| `>` | Greater than | 5 | Left | All data types | No | Boolean |
| `>=` | Greater than or equal | 5 | Left | All data types | No | Boolean |
| `==` | Equality | 4 | Left | All data types | Yes | Boolean |
| `!=` | Inequality | 4 | Left | All data types | Yes | Boolean |
| `&&` | Logical and | 3 | Left | All data types | No | Boolean |
| `\|\|` | Logical or | 2 | Left | All data types | No | Boolean |

Parenthesis `(` and `)` can be used to change the precedence of operations. Variables, constants, and functions have a precedence of 1 and left associativity.

Supported constants:

- `E` - Euler's constant and the base of natural logarithms (approx. 2.718)
- `LN2` - natural logarithm of 2 (approx. 0.693)
- `LN10` - natural logarithm of 10 (approx. 2.303)
- `LOG2E` - base-2 logarithm of `E` (approx. 1.443)
- `PI` - ratio of a circle's circumference to its diameter (approx. 3.14159)
- `SQRT1_2` - square root of ½ (approx. 0.707)
- `SQRT2` - square root of 2 (approx. 1.414)

Supported numeric constant formats:

- Decimal, e.g., `123` or `1.123`
- Binary (base 2), e.g., `0b1010`
- Octal (base 8), e.g., `0o1234567`
- Hexadecimal (base 16), e.g., `0x123af`
- Scientific notation, e.g., `1.123e+3`

Supported string literal formats:

- Single quotation marks, e.g., `'Column'`
- Double quotation marks, e.g., `"Column"`
- Backticks, e.g., `` `Column` ``

Supported boolean formats:

- True, e.g., `true`
- False, e.g., `false`

Supported null format:

- Null, e.g., `null`

An escape character `\` can be used to escape special characters in string literals. Supported escape sequences:

- `\'` - single quotation mark
- `\"` - double quotation mark
- `` \` `` - backtick
- `\\` - backslash
- `\n` - newline character
- `\t` - tab character

If an unsupported escape sequence is found, then the escape character is dropped, e.g., `\d` becomes `d`.

Supported numerical functions:

- `abs(x)` - returns the absolute value of `x`
- `acos(x)` - returns the arccosine of `x`
- `acosh(x)` - returns the hyperbolic arccosine of `x`
- `asin(x)` - returns the arcsine of `x`
- `asinh(x)` - returns the hyperbolic arcsine of `x`
- `atan(x)` - returns the arctangent of `x`
- `atanh(x)` - returns the hyperbolic arctangent of `x`
- `atan2(y, x)` - returns the arctangent of the quotient of `y` divided by `x`
- `cbrt(x)` - returns the cube root of `x`
- `ceil(x)` - returns the smallest integer greater than or equal to `x`
- `clz32(x)` - returns the number of leading zero bits of the 32-bit integer `x`
- `cos(x)` - returns the cosine of `x`
- `cosh(x)` - returns the hyperbolic cosine of `x`
- `exp(x)` - returns `E ** x` or `pow(E, x)`, where `x` is the argument, and `E` is Euler's constant (2.718…, the base of the natural logarithm)
- `expm1(x)` - returns subtracting 1 from `exp(x)`
- `floor(x)` - returns the largest integer less than or equal to `x`
- `fround(x)` - returns the nearest single precision float representation of `x`
- `hypot(x, y[, z[, …]])` - returns the square root of the sum of squares of its arguments
- `imul(x, y)` - returns the result of the 32-bit integer multiplication of `x` and `y`
- `log(x)` - returns the natural logarithm of `x`
- `log1p(x)` - returns the natural logarithm of `1 + x`
- `log10(x)` - returns the base-10 logarithm of `x`
- `log2(x)` - returns the base-2 logarithm of `x`
- `max(x, y[, z[, …]])` - returns the largest of 2 or more numbers
- `min(x, y[, z[, …]])` - returns the smallest of 2 or more numbers
- `pow(x, y)` - returns base `x` to the exponent power `y` (i.e., `x**y`)
- `random()` - returns a pseudo-random number between 0 and 1. The value only changes between different output tables. All rows within a single output table get the same value
- `round(x)` - returns the value of the number `x` rounded to the nearest integer
- `sign(x)` - returns the sign of the `x`, indicating whether `x` is positive (`1`), negative (`-1`), or zero (`0`)
- `sin(x)` - returns the sine of `x`
- `sinh(x)` - returns the hyperbolic sine of `x`
- `sqrt(x)` - returns the positive square root of `x`
- `tan(x)` - returns the tangent of `x`
- `tanh(x)` - returns the hyperbolic tangent of `x`
- `trunc(x)` - returns the integer portion of `x`, removing any fractional digits

Supported string functions:

- `charat(str, index)` - returns exactly one character at the specified index. Accepts negative integers, which count back from the last string character
- `concat(str , ...strN)` - combines the text of two (or more) strings and returns a new string
- `padend(str, targetLength [, padString])` - pads the given string from the end with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `padstart(str, targetLength [, padString])` - pads the given string from the start with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `substring(str, beginIndex [, endIndex])` - returns a new string containing characters of `str` from (or between) the specified index (or indices)
- `tolowercase(str)` - returns the `str` value converted to lowercase
- `touppercase(str)` - returns the `str` value converted to uppercase
- `trim(str)` - trims whitespace from the beginning and end of `str`
- `trimstart(str)` - trims whitespace from beginning of `str`
- `trimend(str)` - trims whitespace from end of `str`

Supported conditional functions:

- `if(cond, expr_true, expr_false)` - returns `expr_true` if `cond` is `true` else it returns `expr_false`. `expr_true` and `expr_false` must be of the same type. `expr_true` and `expr_false` can be `null`
- `ifnull(var, expr)` - returns `expr` if `var` is `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifnotnull(var, expr)` - returns `expr` if `var` is not `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifempty(str, expr)` - returns `expr` if `str` is empty else it returns `str`. `str` and `expr` must be strings
- `ifnotempty(str, expr)` - returns `expr` if `str` is not empty else it returns `str`. `str` and `expr` must be strings
- `ifnullorempty(str, expr)` - returns `expr` if `str` is null or empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorempty(str, expr)` - returns `expr` if `str` is not null and not empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnullorwhitespace(str, expr)` - returns `expr` if `str` is null or empty or only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorwhitespace(str, expr)` - returns `expr` if `str` is not null and not empty and not only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`

Examples of supported formulas:

- `min(A * B, B * C, A * C)` - if `A`, `B`, and `C` are 3 different lengths of box edges, then this formula will result in the smallest side surface area of that box
- `min * max` - formula does not have parenthesis after function names, so the `min` and `max` operands are treated as variables (other columns), not as functions. If the Group has columns `min` and `max`, and their values are `2` and `5`, then the result of this formula is `10` for that row
- `2 ** 3` - 2 raised to the power of 3. Result will be 8. This can also be written as `pow(2, 3)`
- `min(cos(X), sin(X))` - function nesting is supported
- `A * (B + C)` - `A` multiplied by the sum of `B` and `C`
- `A * B + C` - same as `(A * B) + C`
- `padend(concat(A, '\\', touppercase(substring(B, 4))), C, D)` - the result of `concat`, which concatenates variable `A`, string literal `\` and `uppercase` `substring` of variable `B` from index `4`, is padded in the end with the target length of `C` with a pad string of variable `D`
- `charat(trim(A), B)` - gets the character of a trimmed string variable `A` that is at index `B`
- `if(A > B, A, B)` - if `A` is greater than `B` then the result is `A` else it is `B`
- `ifnullorempty(A, 'B = ') + B` - if variable `A` is null or empty then the result of `ifnullorempty` function is the string literal `B = ` else it is variable `A`. Then the final formula result is the addition of the result of `ifnullorempty` function and variable `B`
- `if(A != null && B != null, A + B, 0)` - if `A` is not null and `B` is not null then the result is the addition of `A` and `B` else it is `0`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-customcalculations

Retrieved CustomCalculations successfully.

---

Gets a Group for a Mapping.

### Group Query

The `query` parameter of a Group supports ECSql and ECClassIds.

If a valid ECSql query is given and the selected class is `bis.Element`, or if it is a descendant of the class `bis.Element`, the only required column is `ECInstanceId`.

- `SELECT * FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT * FROM Building.Beam` is a valid query
- `SELECT ECInstanceId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId FROM Building.Beam` is valid
- `SELECT ECClassId FROM bis.Element` is _not_ a valid query because ECInstanceId column is missing
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECClassId FROM Building.Beam` is _not_ valid because ECInstanceId column is missing
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.ECInstanceId FROM bis.Element E JOIN Building.BeamAspect A ON A.Element.id = E.ECInstanceId` is _not_ valid because the selected `ECInstanceId` is of the aspect, not the element
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id FROM Building.BeamAspect` is _not_ valid because the selected column's name is not `ECInstanceId`
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases when providing an ECSql query it is required to select `ECInstanceId`, `ECClassId`, and all other columns that you are planning to use for mapping. If only `ECInstanceId` and `ECClassId` are selected and other columns are used for mapping, those columns will be filled with `null` values. If either `ECInstanceId` or `ECClassId` column is not selected, the query will not produce any output.

If the `query` parameter does not contain a valid ECSql query, then it must be equal to `bis.Element`, `bis.ElementAspect`, or any of their descendants.

The ECClassId format `{schemaName}:{schemaItemName}` where `schemaName` does not contain a 3-part version number is supported.

The ECClassId format `{schemaName}.{schemaItemName}` is supported.

The ECClassId format `{schemaAlias}:{schemaItemName}` where `schemaAlias` is the alias of a `schemaName` is supported.

The ECClassId format `{schemaFullName}:{schemaItemName}` where `schemaFullName` contains a 3-part version number is _not_ supported.

When the given ECClassId is equal to `bis.Element` or is one of its descendants, then all elements with the ECClassId will be selected.

When the given ECClassId is equal to `bis.ElementAspect` or is one of its descendants, then all elements that have such aspect will be selected.

When the given ECClassId is none of the above, the query will not produce any output.

- If a class `Building.Beam` does not have any subclasses and the `query` parameter is set to `Building.Beam`, then all elements with ECClassIds of `Building.Beam` will be selected
- If there is a class `Building.StructuralMember` which has 2 subclasses `Building.Beam` and `Building.Column`, and the `query` parameter is set to `Building.StructuralMember`, then all elements with ECClassIds of `Building.StructuralMember`, `Building.Beam`, and `Building.Column` will be selected
- If a class `Building.BeamAspect` inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.BeamAspect`, then all elements that have a `Building.BeamAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId
- If there is class `Building.StructuralMemberAspect` which has 2 subclasses `Building.BeamAspect` and `Building.ColumnAspect`, the `Building.StructuralMemberAspect` class inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.StructuralMemberAspect`, then all elements that have `Building.StructuralMemberAspect`, `Building.BeamAspect`, or `Building.ColumnAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId

If different queries are needed for a single output table, then create multiple Groups with those different queries but with the same name for each Group. That will cause results of all these queries to be concatenated into a single output table. The output table will have column list equal to a union of all GroupProperties of Groups with the same name.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-group

---

Gets all GroupProperties for a Group.

### Mapping ECProperties

GroupProperties define mappings from ECProperties on an iModel to columns. They allow mapping the queried, element, element aspect, or related element properties.

Content of the columns depend on the `ecProperties` field. The `ecProperties` field is a prioritized array which contains `ECProperty` entities. The closer the `ECProperty` is to the array's start, the higher the priority. The priority of `ECProperty` can be changed by reordering the `ecProperties` array. Reading of the `ecProperties` array stops when a valid value is found. For example, if the `ecProperties` array contains two entries and the first entry results in a null or undefined value, it will take the second entry. The value can be undefined if the given ECProperty does not exist. The result column will be filled with a null value if no valid value was found.

Evaluating `ecProperties` is prioritized by:

1. Queried properties
2. Element properties
3. Element aspect properties

Having queried properties as the highest priority allows for constant or complex values to be added to a mapping.

`ECProperty` lookup is defined by three values - `ECSchemaName`, `ECClassName`, and `ECPropertyName`.

`ECSchemaName` and `ECClassName` are used together to create a ECClassId which is the ECClassId of the current row when selecting a property. If the ECClassId of a selected row does not match the `ECSchemaName` and `ECClassName` pair, the value for this `ECProperty` is considered undefined. If the formed ECClassId is of an element aspect, the current selected row is an element and there is only one instance of that element aspect related to the element, the property lookup is done on the element aspect.

`ECSchemaName` and `ECClassName` are case-insensitive.

`ECSchemaName` and `ECClassName` can be set to a wildcard value `*`.

- If the value of `ECSchemaName` is `*` and the value of `ECClassName` is `Beam`, then it will match any `Beam` class from any schema (e.g. `Building.Beam`, `Structural.Beam`, etc.)
- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `*`, then it will match any class from the schema `Building` (e.g. `Building.Beam`, `Building.CurtainWall`, etc.)
- If values of `ECSchemaName` and `ECClassName` are `*`, then it will match any ECClassId (e.g. `Building.Beam`, `Structural.Column`, etc.)
- If either value of `ECSchemaName` or `ECClassName` are `*`, then no element aspect lookup is done

Class inheritance is checked if there is no wildcard value.

- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `StructuralMember`, then it will match any ECClassId which inherits `Building.StructuralMember` (e.g. `Building.Beam` which inherits `Building.StructuralMember`, `Building.Column` which inherits `Building.StructuralMember`, etc)
- If `ECSchemaName` or `ECClassName` is a wildcard, then inheritance will not be checked

Set `ECPropertyName` to a property name that you want to select. The value of `ECPropertyName` can also be a path defining how to find a property. The path segments must be separated by a period (`.`). The path can contain the names of:

- A navigation property
- A struct property
- A string property that happens to contain a string representation of a json object
- A property inside the selected json

Names of properties are not case sensitive. If json object does not have duplicate property names which only differ in letter casing, then those json properties are not case sensitive. We recommend treating json properties as case sensitive.

- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category` or `category`, then the whole value `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` will be selected
- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category.id`, then only the `id` value `0x2000000000b` will be selected
- If `Category` property is a navigation property and it points to a row that has a property `CodeValue` that we want to select, the `ECPropertyName` should be set to `Category.CodeValue`
- If `Model` property is a navigation property and it points to a row that has a property `JsonProperties` with a value `{"formatter":{"mastUnit":{"label":"m"}}}` and we want to select the master unit label, the `ECPropertyName` should be set to `Model.JsonProperties.formatter.mastUnit.label`. The result will be `m`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-groupproperties

---

Gets a GroupProperty for a Group.

### Mapping ECProperties

GroupProperties define mappings from ECProperties on an iModel to columns. They allow mapping the queried, element, element aspect, or related element properties.

Content of the columns depend on the `ecProperties` field. The `ecProperties` field is a prioritized array which contains `ECProperty` entities. The closer the `ECProperty` is to the array's start, the higher the priority. The priority of `ECProperty` can be changed by reordering the `ecProperties` array. Reading of the `ecProperties` array stops when a valid value is found. For example, if the `ecProperties` array contains two entries and the first entry results in a null or undefined value, it will take the second entry. The value can be undefined if the given ECProperty does not exist. The result column will be filled with a null value if no valid value was found.

Evaluating `ecProperties` is prioritized by:

1. Queried properties
2. Element properties
3. Element aspect properties

Having queried properties as the highest priority allows for constant or complex values to be added to a mapping.

`ECProperty` lookup is defined by three values - `ECSchemaName`, `ECClassName`, and `ECPropertyName`.

`ECSchemaName` and `ECClassName` are used together to create a ECClassId which is the ECClassId of the current row when selecting a property. If the ECClassId of a selected row does not match the `ECSchemaName` and `ECClassName` pair, the value for this `ECProperty` is considered undefined. If the formed ECClassId is of an element aspect, the current selected row is an element and there is only one instance of that element aspect related to the element, the property lookup is done on the element aspect.

`ECSchemaName` and `ECClassName` are case-insensitive.

`ECSchemaName` and `ECClassName` can be set to a wildcard value `*`.

- If the value of `ECSchemaName` is `*` and the value of `ECClassName` is `Beam`, then it will match any `Beam` class from any schema (e.g. `Building.Beam`, `Structural.Beam`, etc.)
- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `*`, then it will match any class from the schema `Building` (e.g. `Building.Beam`, `Building.CurtainWall`, etc.)
- If values of `ECSchemaName` and `ECClassName` are `*`, then it will match any ECClassId (e.g. `Building.Beam`, `Structural.Column`, etc.)
- If either value of `ECSchemaName` or `ECClassName` are `*`, then no element aspect lookup is done

Class inheritance is checked if there is no wildcard value.

- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `StructuralMember`, then it will match any ECClassId which inherits `Building.StructuralMember` (e.g. `Building.Beam` which inherits `Building.StructuralMember`, `Building.Column` which inherits `Building.StructuralMember`, etc)
- If `ECSchemaName` or `ECClassName` is a wildcard, then inheritance will not be checked

Set `ECPropertyName` to a property name that you want to select. The value of `ECPropertyName` can also be a path defining how to find a property. The path segments must be separated by a period (`.`). The path can contain the names of:

- A navigation property
- A struct property
- A string property that happens to contain a string representation of a json object
- A property inside the selected json

Names of properties are not case sensitive. If json object does not have duplicate property names which only differ in letter casing, then those json properties are not case sensitive. We recommend treating json properties as case sensitive.

- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category` or `category`, then the whole value `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` will be selected
- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category.id`, then only the `id` value `0x2000000000b` will be selected
- If `Category` property is a navigation property and it points to a row that has a property `CodeValue` that we want to select, the `ECPropertyName` should be set to `Category.CodeValue`
- If `Model` property is a navigation property and it points to a row that has a property `JsonProperties` with a value `{"formatter":{"mastUnit":{"label":"m"}}}` and we want to select the master unit label, the `ECPropertyName` should be set to `Model.JsonProperties.formatter.mastUnit.label`. The result will be `m`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-groupproperty

---

Gets all Groups for a Mapping.

### Group Query

The `query` parameter of a Group supports ECSql and ECClassIds.

If a valid ECSql query is given and the selected class is `bis.Element`, or if it is a descendant of the class `bis.Element`, the only required column is `ECInstanceId`.

- `SELECT * FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT * FROM Building.Beam` is a valid query
- `SELECT ECInstanceId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId FROM Building.Beam` is valid
- `SELECT ECClassId FROM bis.Element` is _not_ a valid query because ECInstanceId column is missing
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECClassId FROM Building.Beam` is _not_ valid because ECInstanceId column is missing
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.ECInstanceId FROM bis.Element E JOIN Building.BeamAspect A ON A.Element.id = E.ECInstanceId` is _not_ valid because the selected `ECInstanceId` is of the aspect, not the element
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id FROM Building.BeamAspect` is _not_ valid because the selected column's name is not `ECInstanceId`
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases when providing an ECSql query it is required to select `ECInstanceId`, `ECClassId`, and all other columns that you are planning to use for mapping. If only `ECInstanceId` and `ECClassId` are selected and other columns are used for mapping, those columns will be filled with `null` values. If either `ECInstanceId` or `ECClassId` column is not selected, the query will not produce any output.

If the `query` parameter does not contain a valid ECSql query, then it must be equal to `bis.Element`, `bis.ElementAspect`, or any of their descendants.

The ECClassId format `{schemaName}:{schemaItemName}` where `schemaName` does not contain a 3-part version number is supported.

The ECClassId format `{schemaName}.{schemaItemName}` is supported.

The ECClassId format `{schemaAlias}:{schemaItemName}` where `schemaAlias` is the alias of a `schemaName` is supported.

The ECClassId format `{schemaFullName}:{schemaItemName}` where `schemaFullName` contains a 3-part version number is _not_ supported.

When the given ECClassId is equal to `bis.Element` or is one of its descendants, then all elements with the ECClassId will be selected.

When the given ECClassId is equal to `bis.ElementAspect` or is one of its descendants, then all elements that have such aspect will be selected.

When the given ECClassId is none of the above, the query will not produce any output.

- If a class `Building.Beam` does not have any subclasses and the `query` parameter is set to `Building.Beam`, then all elements with ECClassIds of `Building.Beam` will be selected
- If there is a class `Building.StructuralMember` which has 2 subclasses `Building.Beam` and `Building.Column`, and the `query` parameter is set to `Building.StructuralMember`, then all elements with ECClassIds of `Building.StructuralMember`, `Building.Beam`, and `Building.Column` will be selected
- If a class `Building.BeamAspect` inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.BeamAspect`, then all elements that have a `Building.BeamAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId
- If there is class `Building.StructuralMemberAspect` which has 2 subclasses `Building.BeamAspect` and `Building.ColumnAspect`, the `Building.StructuralMemberAspect` class inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.StructuralMemberAspect`, then all elements that have `Building.StructuralMemberAspect`, `Building.BeamAspect`, or `Building.ColumnAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId

If different queries are needed for a single output table, then create multiple Groups with those different queries but with the same name for each Group. That will cause results of all these queries to be concatenated into a single output table. The output table will have column list equal to a union of all GroupProperties of Groups with the same name.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-groups

---

Gets a Mapping for an iModel.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-mapping

---

Gets all Mappings for an iModel.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-mappings

---

Updates a CalculatedProperty for a Group.

### Calculation Types

Calculation types that start with `BoundingBox` use element aligned bounding boxes. They can be used for approximations of geometric element dimensions when there are no available properties that would have exact dimensions. Some errors may occur due to bounding boxes not being a perfect fit for the surrounded element.

List of all available calculation types:

- `Length` - calculation of a linear element length or a perimeter of a geometric element that does not have a volume. For elements that have a volume use BoundingBox calculations to approximate the length.
- `Area` - calculation of a geometric element's surface area.
- `Volume` - calculation of a geometric element's volume.
- `BoundingBoxLongestEdgeLength` - calculation that gives the longest edge length of an element aligned bounding box.
- `BoundingBoxIntermediateEdgeLength` - calculation that gives the edge length that is not the longest nor the shortest of an element aligned bounding box.
- `BoundingBoxShortestEdgeLength` - calculation that gives the shortest edge length of an element aligned bounding box.
- `BoundingBoxDiagonalLength` - calculation that gives the distance between 2 opposite corners of the element aligned bounding box.
- `BoundingBoxLongestFaceDiagonalLength` - calculation that gives the longest distance between 2 opposite corners of a face on the element aligned bounding box.
- `BoundingBoxIntermediateFaceDiagonalLength` - calculation that gives the distance between 2 opposite corners of a face on the element aligned bounding box that is not the longest nor the shortest.
- `BoundingBoxShortestFaceDiagonalLength` - calculation that gives the shortest distance between 2 opposite corners of a face on the element aligned bounding box.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


update-calculatedproperty

Id of the CalculatedProperty to be updated.

Updated a CalculatedProperty successfully.

---

Updates a CustomCalculation for a Group.

### CustomCalculations

CustomCalculation is a type of Group property which contains a formula. CustomCalculation defines a column in the output data that gets filled with the formula evaluation result. The formula is evaluated for each row of the Group's query result during each extraction.

The formula supports using other columns (GroupProperty, CalculatedProperty or CustomCalculation entities) as variables. Recursive formulas are not supported, i.e., formula containing a variable `X` is not supported inside a CustomCalculation with a `propertyName` equal to `X`.

Supported data types:

- Number - describes a real number. When converted to a boolean value in logical operators `0` becomes `false` and all other values become `true`
- Boolean - describes a logical value which is either true or false. When converted to a number in certain operators `true` becomes `1` and `false` becomes `0`
- String - describes text. When converted to a boolean value in logical operators an empty string becomes `false` and all other strings become `true`

All of the supported data types can have no value which means that the value is `null`. Some operations support `null` values but those which do not will return `null` as the result.

Supported operators:

| Symbol | Name | Precedence | Associativity | Operand Types | Can receive null | Result |
|--|--|--|--|--|--|--|
| Unary `-` | Unary negation | 9 | Right | Numbers and booleans | No | Number |
| `!` | Logical not | 9 | Right | All data types | No | Boolean |
| `**` | Exponentiation | 8 | Right | Numbers and booleans | No | Number |
| `*` | Multiplication | 7 | Left | Numbers and booleans | No | Number |
| `/` | Division | 7 | Left | Numbers and booleans | No | Number |
| `%` | Remainder | 7 | Left | Numbers and booleans | No | Number |
| `+` | Addition | 6 | Left | All data types | No | Number or string if one of the operands is a string |
| Binary `-` | Subtraction | 6 | Left | Numbers and booleans | No | Number |
| `<` | Less than | 5 | Left | All data types | No | Boolean |
| `<=` | Less than or equal | 5 | Left | All data types | No | Boolean |
| `>` | Greater than | 5 | Left | All data types | No | Boolean |
| `>=` | Greater than or equal | 5 | Left | All data types | No | Boolean |
| `==` | Equality | 4 | Left | All data types | Yes | Boolean |
| `!=` | Inequality | 4 | Left | All data types | Yes | Boolean |
| `&&` | Logical and | 3 | Left | All data types | No | Boolean |
| `\|\|` | Logical or | 2 | Left | All data types | No | Boolean |

Parenthesis `(` and `)` can be used to change the precedence of operations. Variables, constants, and functions have a precedence of 1 and left associativity.

Supported constants:

- `E` - Euler's constant and the base of natural logarithms (approx. 2.718)
- `LN2` - natural logarithm of 2 (approx. 0.693)
- `LN10` - natural logarithm of 10 (approx. 2.303)
- `LOG2E` - base-2 logarithm of `E` (approx. 1.443)
- `PI` - ratio of a circle's circumference to its diameter (approx. 3.14159)
- `SQRT1_2` - square root of ½ (approx. 0.707)
- `SQRT2` - square root of 2 (approx. 1.414)

Supported numeric constant formats:

- Decimal, e.g., `123` or `1.123`
- Binary (base 2), e.g., `0b1010`
- Octal (base 8), e.g., `0o1234567`
- Hexadecimal (base 16), e.g., `0x123af`
- Scientific notation, e.g., `1.123e+3`

Supported string literal formats:

- Single quotation marks, e.g., `'Column'`
- Double quotation marks, e.g., `"Column"`
- Backticks, e.g., `` `Column` ``

Supported boolean formats:

- True, e.g., `true`
- False, e.g., `false`

Supported null format:

- Null, e.g., `null`

An escape character `\` can be used to escape special characters in string literals. Supported escape sequences:

- `\'` - single quotation mark
- `\"` - double quotation mark
- `` \` `` - backtick
- `\\` - backslash
- `\n` - newline character
- `\t` - tab character

If an unsupported escape sequence is found, then the escape character is dropped, e.g., `\d` becomes `d`.

Supported numerical functions:

- `abs(x)` - returns the absolute value of `x`
- `acos(x)` - returns the arccosine of `x`
- `acosh(x)` - returns the hyperbolic arccosine of `x`
- `asin(x)` - returns the arcsine of `x`
- `asinh(x)` - returns the hyperbolic arcsine of `x`
- `atan(x)` - returns the arctangent of `x`
- `atanh(x)` - returns the hyperbolic arctangent of `x`
- `atan2(y, x)` - returns the arctangent of the quotient of `y` divided by `x`
- `cbrt(x)` - returns the cube root of `x`
- `ceil(x)` - returns the smallest integer greater than or equal to `x`
- `clz32(x)` - returns the number of leading zero bits of the 32-bit integer `x`
- `cos(x)` - returns the cosine of `x`
- `cosh(x)` - returns the hyperbolic cosine of `x`
- `exp(x)` - returns `E ** x` or `pow(E, x)`, where `x` is the argument, and `E` is Euler's constant (2.718…, the base of the natural logarithm)
- `expm1(x)` - returns subtracting 1 from `exp(x)`
- `floor(x)` - returns the largest integer less than or equal to `x`
- `fround(x)` - returns the nearest single precision float representation of `x`
- `hypot(x, y[, z[, …]])` - returns the square root of the sum of squares of its arguments
- `imul(x, y)` - returns the result of the 32-bit integer multiplication of `x` and `y`
- `log(x)` - returns the natural logarithm of `x`
- `log1p(x)` - returns the natural logarithm of `1 + x`
- `log10(x)` - returns the base-10 logarithm of `x`
- `log2(x)` - returns the base-2 logarithm of `x`
- `max(x, y[, z[, …]])` - returns the largest of 2 or more numbers
- `min(x, y[, z[, …]])` - returns the smallest of 2 or more numbers
- `pow(x, y)` - returns base `x` to the exponent power `y` (i.e., `x**y`)
- `random()` - returns a pseudo-random number between 0 and 1. The value only changes between different output tables. All rows within a single output table get the same value
- `round(x)` - returns the value of the number `x` rounded to the nearest integer
- `sign(x)` - returns the sign of the `x`, indicating whether `x` is positive (`1`), negative (`-1`), or zero (`0`)
- `sin(x)` - returns the sine of `x`
- `sinh(x)` - returns the hyperbolic sine of `x`
- `sqrt(x)` - returns the positive square root of `x`
- `tan(x)` - returns the tangent of `x`
- `tanh(x)` - returns the hyperbolic tangent of `x`
- `trunc(x)` - returns the integer portion of `x`, removing any fractional digits

Supported string functions:

- `charat(str, index)` - returns exactly one character at the specified index. Accepts negative integers, which count back from the last string character
- `concat(str , ...strN)` - combines the text of two (or more) strings and returns a new string
- `padend(str, targetLength [, padString])` - pads the given string from the end with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `padstart(str, targetLength [, padString])` - pads the given string from the start with a given string and returns a new string of the length `targetLength`. Maximum value of `targetLength` is `100`. The resulting string will be truncated if it is too long to stay within `targetLength`. The default value for `padString` is " " (white space)
- `substring(str, beginIndex [, endIndex])` - returns a new string containing characters of `str` from (or between) the specified index (or indices)
- `tolowercase(str)` - returns the `str` value converted to lowercase
- `touppercase(str)` - returns the `str` value converted to uppercase
- `trim(str)` - trims whitespace from the beginning and end of `str`
- `trimstart(str)` - trims whitespace from beginning of `str`
- `trimend(str)` - trims whitespace from end of `str`

Supported conditional functions:

- `if(cond, expr_true, expr_false)` - returns `expr_true` if `cond` is `true` else it returns `expr_false`. `expr_true` and `expr_false` must be of the same type. `expr_true` and `expr_false` can be `null`
- `ifnull(var, expr)` - returns `expr` if `var` is `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifnotnull(var, expr)` - returns `expr` if `var` is not `null` else it returns `var`. `var` and `expr` must be of the same type. `var` can be `null`
- `ifempty(str, expr)` - returns `expr` if `str` is empty else it returns `str`. `str` and `expr` must be strings
- `ifnotempty(str, expr)` - returns `expr` if `str` is not empty else it returns `str`. `str` and `expr` must be strings
- `ifnullorempty(str, expr)` - returns `expr` if `str` is null or empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorempty(str, expr)` - returns `expr` if `str` is not null and not empty else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnullorwhitespace(str, expr)` - returns `expr` if `str` is null or empty or only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`
- `ifnotnullorwhitespace(str, expr)` - returns `expr` if `str` is not null and not empty and not only consists of whitespace else it returns `str`. `str` and `expr` must be strings. `str` can be `null`

Examples of supported formulas:

- `min(A * B, B * C, A * C)` - if `A`, `B`, and `C` are 3 different lengths of box edges, then this formula will result in the smallest side surface area of that box
- `min * max` - formula does not have parenthesis after function names, so the `min` and `max` operands are treated as variables (other columns), not as functions. If the Group has columns `min` and `max`, and their values are `2` and `5`, then the result of this formula is `10` for that row
- `2 ** 3` - 2 raised to the power of 3. Result will be 8. This can also be written as `pow(2, 3)`
- `min(cos(X), sin(X))` - function nesting is supported
- `A * (B + C)` - `A` multiplied by the sum of `B` and `C`
- `A * B + C` - same as `(A * B) + C`
- `padend(concat(A, '\\', touppercase(substring(B, 4))), C, D)` - the result of `concat`, which concatenates variable `A`, string literal `\` and `uppercase` `substring` of variable `B` from index `4`, is padded in the end with the target length of `C` with a pad string of variable `D`
- `charat(trim(A), B)` - gets the character of a trimmed string variable `A` that is at index `B`
- `if(A > B, A, B)` - if `A` is greater than `B` then the result is `A` else it is `B`
- `ifnullorempty(A, 'B = ') + B` - if variable `A` is null or empty then the result of `ifnullorempty` function is the string literal `B = ` else it is variable `A`. Then the final formula result is the addition of the result of `ifnullorempty` function and variable `B`
- `if(A != null && B != null, A + B, 0)` - if `A` is not null and `B` is not null then the result is the addition of `A` and `B` else it is `0`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


update-customcalculation

Id of the CustomCalculation to be updated.

Updated a CustomCalculation successfully.

---

Updates a Group for a Mapping.

### Group Query

The `query` parameter of a Group supports ECSql and ECClassIds.

If a valid ECSql query is given and the selected class is `bis.Element`, or if it is a descendant of the class `bis.Element`, the only required column is `ECInstanceId`.

- `SELECT * FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT * FROM Building.Beam` is a valid query
- `SELECT ECInstanceId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId FROM Building.Beam` is valid
- `SELECT ECClassId FROM bis.Element` is _not_ a valid query because ECInstanceId column is missing
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECClassId FROM Building.Beam` is _not_ valid because ECInstanceId column is missing
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.ECInstanceId FROM bis.Element E JOIN Building.BeamAspect A ON A.Element.id = E.ECInstanceId` is _not_ valid because the selected `ECInstanceId` is of the aspect, not the element
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id FROM Building.BeamAspect` is _not_ valid because the selected column's name is not `ECInstanceId`
- Assuming that `Building.BeamAspect` is an aspect, the query `SELECT A.Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases when providing an ECSql query it is required to select `ECInstanceId`, `ECClassId`, and all other columns that you are planning to use for mapping. If only `ECInstanceId` and `ECClassId` are selected and other columns are used for mapping, those columns will be filled with `null` values. If either `ECInstanceId` or `ECClassId` column is not selected, the query will not produce any output.

If the `query` parameter does not contain a valid ECSql query, then it must be equal to `bis.Element`, `bis.ElementAspect`, or any of their descendants.

The ECClassId format `{schemaName}:{schemaItemName}` where `schemaName` does not contain a 3-part version number is supported.

The ECClassId format `{schemaName}.{schemaItemName}` is supported.

The ECClassId format `{schemaAlias}:{schemaItemName}` where `schemaAlias` is the alias of a `schemaName` is supported.

The ECClassId format `{schemaFullName}:{schemaItemName}` where `schemaFullName` contains a 3-part version number is _not_ supported.

When the given ECClassId is equal to `bis.Element` or is one of its descendants, then all elements with the ECClassId will be selected.

When the given ECClassId is equal to `bis.ElementAspect` or is one of its descendants, then all elements that have such aspect will be selected.

When the given ECClassId is none of the above, the query will not produce any output.

- If a class `Building.Beam` does not have any subclasses and the `query` parameter is set to `Building.Beam`, then all elements with ECClassIds of `Building.Beam` will be selected
- If there is a class `Building.StructuralMember` which has 2 subclasses `Building.Beam` and `Building.Column`, and the `query` parameter is set to `Building.StructuralMember`, then all elements with ECClassIds of `Building.StructuralMember`, `Building.Beam`, and `Building.Column` will be selected
- If a class `Building.BeamAspect` inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.BeamAspect`, then all elements that have a `Building.BeamAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId
- If there is class `Building.StructuralMemberAspect` which has 2 subclasses `Building.BeamAspect` and `Building.ColumnAspect`, the `Building.StructuralMemberAspect` class inherits from a class `bis.ElementAspect` (is unique or multi aspect) and the `query` parameter is set to `Building.StructuralMemberAspect`, then all elements that have `Building.StructuralMemberAspect`, `Building.BeamAspect`, or `Building.ColumnAspect` attached to them will be selected. This query will _not_ select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId

If different queries are needed for a single output table, then create multiple Groups with those different queries but with the same name for each Group. That will cause results of all these queries to be concatenated into a single output table. The output table will have column list equal to a union of all GroupProperties of Groups with the same name.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


update-group

Globally Unique Identifier of the target Mapping.

---

Updates a GroupProperty for a Group.

### Mapping ECProperties

GroupProperties define mappings from ECProperties on an iModel to columns. They allow mapping the queried, element, element aspect, or related element properties.

Content of the columns depend on the `ecProperties` field. The `ecProperties` field is a prioritized array which contains `ECProperty` entities. The closer the `ECProperty` is to the array's start, the higher the priority. The priority of `ECProperty` can be changed by reordering the `ecProperties` array. Reading of the `ecProperties` array stops when a valid value is found. For example, if the `ecProperties` array contains two entries and the first entry results in a null or undefined value, it will take the second entry. The value can be undefined if the given ECProperty does not exist. The result column will be filled with a null value if no valid value was found.

Evaluating `ecProperties` is prioritized by:

1. Queried properties
2. Element properties
3. Element aspect properties

Having queried properties as the highest priority allows for constant or complex values to be added to a mapping.

`ECProperty` lookup is defined by three values - `ECSchemaName`, `ECClassName`, and `ECPropertyName`.

`ECSchemaName` and `ECClassName` are used together to create a ECClassId which is the ECClassId of the current row when selecting a property. If the ECClassId of a selected row does not match the `ECSchemaName` and `ECClassName` pair, the value for this `ECProperty` is considered undefined. If the formed ECClassId is of an element aspect, the current selected row is an element and there is only one instance of that element aspect related to the element, the property lookup is done on the element aspect.

`ECSchemaName` and `ECClassName` are case-insensitive.

`ECSchemaName` and `ECClassName` can be set to a wildcard value `*`.

- If the value of `ECSchemaName` is `*` and the value of `ECClassName` is `Beam`, then it will match any `Beam` class from any schema (e.g. `Building.Beam`, `Structural.Beam`, etc.)
- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `*`, then it will match any class from the schema `Building` (e.g. `Building.Beam`, `Building.CurtainWall`, etc.)
- If values of `ECSchemaName` and `ECClassName` are `*`, then it will match any ECClassId (e.g. `Building.Beam`, `Structural.Column`, etc.)
- If either value of `ECSchemaName` or `ECClassName` are `*`, then no element aspect lookup is done

Class inheritance is checked if there is no wildcard value.

- If the value of `ECSchemaName` is `Building` and the value of `ECClassName` is `StructuralMember`, then it will match any ECClassId which inherits `Building.StructuralMember` (e.g. `Building.Beam` which inherits `Building.StructuralMember`, `Building.Column` which inherits `Building.StructuralMember`, etc)
- If `ECSchemaName` or `ECClassName` is a wildcard, then inheritance will not be checked

Set `ECPropertyName` to a property name that you want to select. The value of `ECPropertyName` can also be a path defining how to find a property. The path segments must be separated by a period (`.`). The path can contain the names of:

- A navigation property
- A struct property
- A string property that happens to contain a string representation of a json object
- A property inside the selected json

Names of properties are not case sensitive. If json object does not have duplicate property names which only differ in letter casing, then those json properties are not case sensitive. We recommend treating json properties as case sensitive.

- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category` or `category`, then the whole value `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` will be selected
- If `Category` property is a navigation property with a value of `{"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"}` and the `ECPropertyName` is set to `Category.id`, then only the `id` value `0x2000000000b` will be selected
- If `Category` property is a navigation property and it points to a row that has a property `CodeValue` that we want to select, the `ECPropertyName` should be set to `Category.CodeValue`
- If `Model` property is a navigation property and it points to a row that has a property `JsonProperties` with a value `{"formatter":{"mastUnit":{"label":"m"}}}` and we want to select the master unit label, the `ECPropertyName` should be set to `Model.JsonProperties.formatter.mastUnit.label`. The result will be `m`

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


update-groupproperty

---

Updates a Mapping for an iModel.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_write` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

### Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


update-mapping

---

Creates a Report within the context of a Project.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_modify` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


create-report

---

Creates a Report Mapping. Each one links a Mapping to a Report and each Report can have more than one Report Mapping. 

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `imodels_read`, `insights_modify` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


create-report-mapping

Created a new Report Mapping successfully.

---

Marks a Report for deletetion. Reports are permanently deleted one month after being marked for deletion. A Report marked for deletion can be restored if it hasn't been permanently deleted yet.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_modify` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


delete-report

Report was marked for deletion. Report will be permanently deleted one month after being marked for deletion.

---

Deletes a Report Mapping from a Report.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_modify` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


delete-report-mapping

---

Gets all Reports within the context of a Project.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_view` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-project-reports

projectId

Optionally filter Reports by those marked for deletion. NOTE: Reports marked for deletion will be permanently deleted after 1 month unless deletion is reverted.

deleted

Fetched all project Reports successfully.

---

Gets a single Report.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_view` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-report

---

Gets all Report Mappings for a Report.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_view` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---


get-report-mappings

---

Updates a Report.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `insights:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_modify` permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities [Licensing, Cloud, and Web Services](https://communities.bentley.com/communities/other_communities/licensing_cloud_and_web_services/w/wiki/50711/user-management-2-0) wiki page.

### Rate limits

All iTwin Platform API operations have a rate limit. For more documentation on that visit [Rate limits and quotas](https://developer.bentley.com/apis/overview/rate-limits/) page.

---
