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

insights-v2

---

Creates an aggregation property.

Aggregation property defines how the aggregation should be done. There are 3 supported types: `GroupBy`, `Count`, and `Sum`.

`GroupBy` aggregation property type splits the data source table into groups that have matching values in the column specified in `sourcePropertyName`. If you will not create a `GroupBy` property our aggregator will assume that the whole data source table is one group. If you will create multiple `GroupBy` properties targeting different data source properties each group will have a unique combination of those properties. See example configuration and output table `T3` below.

`Count` aggregation property type counts how many rows there are in a group. If the value of property specified in `sourcePropertyName` contains a `null` value in data source table, the row is still counted.

`Sum` aggregation property type sums all values of a single property in a single group.

### Examples

Let's say you have this data source table:

| A | B | C | D |
|--|--|--|--|
| a1 | b1 | 1 | null |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 4 | 2 |
| a2 | b2 | 8 | 4 |

&nbsp;
&nbsp;

Then you have these aggregation table configurations:

- Aggregation properties for table `T1`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| CountC | C | Count |
| CountD | D | Count |
| SumC | C | Sum |
| SumD | D | Sum |

&nbsp;
&nbsp;

- Aggregation properties for table `T2`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

- Aggregation properties for table `T3`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| GroupB | B | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

Then your aggregated table outputs will look like this:

- Table `T1`:

| CountC | CountD | SumC | SumD |
|--|--|--|--|
| 4 | 4 | 15 | 7 |

&nbsp;
&nbsp;

- Table `T2`:

| GroupA | SumC | CountC |
|--|--|--|
| a1 | 3 | 2 |
| a2 | 12 | 2 |

&nbsp;
&nbsp;

- Table `T3`:

| GroupA | GroupB | SumC | CountC |
|--|--|--|--|
| a1 | b1 | 1 | 1 |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 12 | 2 |

&nbsp;
&nbsp;

In the `T3` example you can see that groups were created for each unique pair of values in columns `A` and `B`.

### 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.

---


create-aggregationproperty

aggregationTableSetId

aggregationTableId

OAuth access token with scope `insights:modify`

Authorization

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

Accept

default

Created a new AggregationProperty successfully.

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.

HeaderNotFound

application/json;InvalidAuthorizationScheme

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

The user has insufficient permissions for the requested operation.

Specified AggregationTable was not found.

AggregationProperty with the same name already exists within the AggregationTable.

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).

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

---

Creates an aggregation table.

Aggregation table represents a configuration for a single data source table aggregation. One aggregation table will result in one output table. You can have multiple aggregation tables taking data from the same data source table, but aggregation table can only take data from one data source table.

### 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.

---


create-aggregationtable

Created a new AggregationTable successfully.

Specified AggregationTableSet was not found.

---

Creates an aggregation table set for a data source. You will not be able to change data source of an aggregation table set after you create it.

Aggregation table set represents a collection of configurations for data source table aggregation.

### 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.

---


create-aggregationtableset

Created a new AggregationTableSet successfully.

---

Deletes an aggregation property.

### 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.

---


delete-aggregationproperty

aggregationPropertyId

Deleted an AggregationProperty successfully.

Specified AggregationProperty was not found.

---

Deletes an aggregation table.

### 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.

---


delete-aggregationtable

Deleted an AggregationTable successfully.

---

Deletes an aggregation table set.

### 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.

---


delete-aggregationtableset

Deleted an AggregationTableSet successfully.

---

Get all aggregation properties in a given aggregation table.

Aggregation property defines how the aggregation should be done. There are 3 supported types: `GroupBy`, `Count`, and `Sum`.

`GroupBy` aggregation property type splits the data source table into groups that have matching values in the column specified in `sourcePropertyName`. If you will not create a `GroupBy` property our aggregator will assume that the whole data source table is one group. If you will create multiple `GroupBy` properties targeting different data source properties each group will have a unique combination of those properties. See example configuration and output table `T3` below.

`Count` aggregation property type counts how many rows there are in a group. If the value of property specified in `sourcePropertyName` contains a `null` value in data source table, the row is still counted.

`Sum` aggregation property type sums all values of a single property in a single group.

### Examples

Let's say you have this data source table:

| A | B | C | D |
|--|--|--|--|
| a1 | b1 | 1 | null |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 4 | 2 |
| a2 | b2 | 8 | 4 |

&nbsp;
&nbsp;

Then you have these aggregation table configurations:

- Aggregation properties for table `T1`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| CountC | C | Count |
| CountD | D | Count |
| SumC | C | Sum |
| SumD | D | Sum |

&nbsp;
&nbsp;

- Aggregation properties for table `T2`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

- Aggregation properties for table `T3`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| GroupB | B | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

Then your aggregated table outputs will look like this:

- Table `T1`:

| CountC | CountD | SumC | SumD |
|--|--|--|--|
| 4 | 4 | 15 | 7 |

&nbsp;
&nbsp;

- Table `T2`:

| GroupA | SumC | CountC |
|--|--|--|
| a1 | 3 | 2 |
| a2 | 12 | 2 |

&nbsp;
&nbsp;

- Table `T3`:

| GroupA | GroupB | SumC | CountC |
|--|--|--|--|
| a1 | b1 | 1 | 1 |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 12 | 2 |

&nbsp;
&nbsp;

In the `T3` example you can see that groups were created for each unique pair of values in columns `A` and `B`.

### 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-aggregationproperties

Optional max items to be sent in response.

$top

Optional token to retrieve next page in paginated response.

$continuationToken

OAuth access token with scope `insights:read`

Retrieved AggregationProperties successfully.

---

Retrieves an aggregation property.

Aggregation property defines how the aggregation should be done. There are 3 supported types: `GroupBy`, `Count`, and `Sum`.

`GroupBy` aggregation property type splits the data source table into groups that have matching values in the column specified in `sourcePropertyName`. If you will not create a `GroupBy` property our aggregator will assume that the whole data source table is one group. If you will create multiple `GroupBy` properties targeting different data source properties each group will have a unique combination of those properties. See example configuration and output table `T3` below.

`Count` aggregation property type counts how many rows there are in a group. If the value of property specified in `sourcePropertyName` contains a `null` value in data source table, the row is still counted.

`Sum` aggregation property type sums all values of a single property in a single group.

### Examples

Let's say you have this data source table:

| A | B | C | D |
|--|--|--|--|
| a1 | b1 | 1 | null |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 4 | 2 |
| a2 | b2 | 8 | 4 |

&nbsp;
&nbsp;

Then you have these aggregation table configurations:

- Aggregation properties for table `T1`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| CountC | C | Count |
| CountD | D | Count |
| SumC | C | Sum |
| SumD | D | Sum |

&nbsp;
&nbsp;

- Aggregation properties for table `T2`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

- Aggregation properties for table `T3`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| GroupB | B | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

Then your aggregated table outputs will look like this:

- Table `T1`:

| CountC | CountD | SumC | SumD |
|--|--|--|--|
| 4 | 4 | 15 | 7 |

&nbsp;
&nbsp;

- Table `T2`:

| GroupA | SumC | CountC |
|--|--|--|
| a1 | 3 | 2 |
| a2 | 12 | 2 |

&nbsp;
&nbsp;

- Table `T3`:

| GroupA | GroupB | SumC | CountC |
|--|--|--|--|
| a1 | b1 | 1 | 1 |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 12 | 2 |

&nbsp;
&nbsp;

In the `T3` example you can see that groups were created for each unique pair of values in columns `A` and `B`.

### 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-aggregationproperty

Retrieved AggregationProperty successfully.

---

Retrieves an aggregation table.

Aggregation table represents a configuration for a single data source table aggregation. One aggregation table will result in one output table. You can have multiple aggregation tables taking data from the same data source table, but aggregation table can only take data from one data source table.

### 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-aggregationtable

---

Get all aggregation tables for a given aggregation table set id.

Aggregation table represents a configuration for a single data source table aggregation. One aggregation table will result in one output table. You can have multiple aggregation tables taking data from the same data source table, but aggregation table can only take data from one data source table.

### 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-aggregationtables

Retrieved AggregationTables successfully.

---

Retrieves an aggregation table set.

Aggregation table set represents a collection of configurations for data source table aggregation.

### 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-aggregationtableset

Retrieved AggregationTableSet successfully.

---

Get all aggregation table sets for a given data source id.

Aggregation table set represents a collection of configurations for data source table aggregation.

### 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-aggregationtablesets

Id of the data source to query for all its aggregation table sets.

datasourceId

Type of the data source that this aggregation table set works with. Possible values: 'IModelMapping'.

datasourceType

Retrieved AggregationTableSets successfully.

---

Updates an aggregation property.

Aggregation property defines how the aggregation should be done. There are 3 supported types: `GroupBy`, `Count`, and `Sum`.

`GroupBy` aggregation property type splits the data source table into groups that have matching values in the column specified in `sourcePropertyName`. If you will not create a `GroupBy` property our aggregator will assume that the whole data source table is one group. If you will create multiple `GroupBy` properties targeting different data source properties each group will have a unique combination of those properties. See example configuration and output table `T3` below.

`Count` aggregation property type counts how many rows there are in a group. If the value of property specified in `sourcePropertyName` contains a `null` value in data source table, the row is still counted.

`Sum` aggregation property type sums all values of a single property in a single group.

### Examples

Let's say you have this data source table:

| A | B | C | D |
|--|--|--|--|
| a1 | b1 | 1 | null |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 4 | 2 |
| a2 | b2 | 8 | 4 |

&nbsp;
&nbsp;

Then you have these aggregation table configurations:

- Aggregation properties for table `T1`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| CountC | C | Count |
| CountD | D | Count |
| SumC | C | Sum |
| SumD | D | Sum |

&nbsp;
&nbsp;

- Aggregation properties for table `T2`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

- Aggregation properties for table `T3`:

| propertyName | sourcePropertyName | type |
|--|--|--|
| GroupA | A | GroupBy |
| GroupB | B | GroupBy |
| SumC | C | Sum |
| CountC | C | Count |

&nbsp;
&nbsp;

Then your aggregated table outputs will look like this:

- Table `T1`:

| CountC | CountD | SumC | SumD |
|--|--|--|--|
| 4 | 4 | 15 | 7 |

&nbsp;
&nbsp;

- Table `T2`:

| GroupA | SumC | CountC |
|--|--|--|
| a1 | 3 | 2 |
| a2 | 12 | 2 |

&nbsp;
&nbsp;

- Table `T3`:

| GroupA | GroupB | SumC | CountC |
|--|--|--|--|
| a1 | b1 | 1 | 1 |
| a1 | b2 | 2 | 1 |
| a2 | b2 | 12 | 2 |

&nbsp;
&nbsp;

In the `T3` example you can see that groups were created for each unique pair of values in columns `A` and `B`.

### 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.

---


update-aggregationproperty

Updated AggregationProperty successfully.

---

Update an aggregation table.

Aggregation table represents a configuration for a single data source table aggregation. One aggregation table will result in one output table. You can have multiple aggregation tables taking data from the same data source table, but aggregation table can only take data from one data source table.

### 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.

---


update-aggregationtable

Updated aggregation of Group table `Group2`.

---

Update an aggregation table set.

Aggregation table set represents a collection of configurations for data source table aggregation.

### 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.

---


update-aggregationtableset

Updated AggregationTableSet for a mapping

Updated AggregationTableSet successfully.

---

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

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.)

---

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 History of Extraction Runs.

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


get-extraction-history

iModelId

Retrieved Extraction History 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


get-extraction-logs

jobId

Specified Extraction Logs were not found.

---

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](https://www.itwinjs.org/learning/glossary/#imodel).

For the iModel data source, data must be extracted first before it can be used in your reports.

Manual extraction allows you to choose optional request body parameters such as `changesetId`, `mappings`, and `ecInstanceIds`. You can specify the `mappings` list you want to extract, also you can filter `ecInstanceIds` or choose on which `changesetId` to run the new extraction. You can provide any combination of these request body parameters when you send a request.

If you do not provide a request body:
- latest [changeset](https://www.itwinjs.org/learning/glossary/#changeset) will be used for extraction
- all mappings on this iModel with `extractionEnabled` flag set to `true` will be extracted
- all ECInstances will be extracted that are selected by the group queries

### Notes

Data will not be extracted for a mapping if that mapping was already extracted from a newer changeset. If you wish to "go back in time" with a mapping and extract data from an older changeset, you will need to copy the mapping. To see the extracted mapping's data from an older changeset in your report, you will need to update report mappings accordingly.

### Automatic Extraction

For all mappings with `extractionEnabled` set to `true`, iModel data extraction is executed automatically when there are new changes (see [`ChangesetGroupCompletedEvent`](/apis/webhooks/#supportedevents)) to the iModel which are ready to be processed. 

If an iModel contains mappings that have `extractionEnabled` set to `true`, do not call this API on a scheduled basis or after making changes to an iModel. Only call this API after creating or changing an iModel mapping, group, group property, calculated property, or custom calculation. **Note:** Multiple automatic Extractions can be triggered for a single [Synchronization job](/apis/synchronization/).

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

---


run-extraction

---

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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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
- `tonumber(var)` - returns the `var` value converted to a number

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)
- `indexof(str, searchValue [, start])` - returns the index of the first occurance in `str` at which a given string `searchValue` can be found in the array, or -1 if it is not present.
- `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`
- `tostring(var)` - returns the `var` value converted to a string

Supported boolean functions:

- `isin(var, var1[, var2[, ...]])` - returns `true` if `var` is equal to one of `var1, ...varN` else it returns `false`. `var, ...varN` must be of same type
- `toboolean(var)` - returns the `var` value converted to a boolean

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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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 four values - `ECSchemaName`, `ECClassName`, `ECPropertyName` and `ECPropertyType`.

`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`

`ECPropertyType` is case sensitive and corresponds to the data type of a `ECProperty` you want to select. Supported Type values are:

- `Boolean` - describes a logical value which is either true or false,
- `Number` - treated the same as Double,
- `Integer` - describes a whole number,
- `Double` - describes a real number,
- `String` - describes text.

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### Extraction Triggers & Configuration

Mappings can be configured with `extractionEnabled` set to `true` or `false`. `true` means that Extractions will be automatically executed for the given Mapping when either a new ChangesetGroup is created (see [`ChangesetGroupCompletedEvent`](/apis/webhooks/#supportedevents)) or when the [Run Extraction](/apis/insights/operations/run-extraction/) operation is executed without the optional `mappings` parameter. **Note:** Multiple ChangesetGroups can be created for a single [Synchronization job](/apis/synchronization/) which will result in multiple automatic Extractions.

If `extractionEnabled` is set to `false`, all of the above mechanisms are disabled. However, Extractions can still be executed for a specific Mapping manually using the Run Extraction operation and the optional `mappings` parameter. To have better control over Extractions, it is recommended to set `extractionEnabled` to `false` and manually trigger Run Extraction when a Mapping's extracted data is stale and needs to be refreshed.

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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
- `tonumber(var)` - returns the `var` value converted to a number

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)
- `indexof(str, searchValue [, start])` - returns the index of the first occurance in `str` at which a given string `searchValue` can be found in the array, or -1 if it is not present.
- `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`
- `tostring(var)` - returns the `var` value converted to a string

Supported boolean functions:

- `isin(var, var1[, var2[, ...]])` - returns `true` if `var` is equal to one of `var1, ...varN` else it returns `false`. `var, ...varN` must be of same type
- `toboolean(var)` - returns the `var` value converted to a boolean

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
- `tonumber(var)` - returns the `var` value converted to a number

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)
- `indexof(str, searchValue [, start])` - returns the index of the first occurance in `str` at which a given string `searchValue` can be found in the array, or -1 if it is not present.
- `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`
- `tostring(var)` - returns the `var` value converted to a string

Supported boolean functions:

- `isin(var, var1[, var2[, ...]])` - returns `true` if `var` is equal to one of `var1, ...varN` else it returns `false`. `var, ...varN` must be of same type
- `toboolean(var)` - returns the `var` value converted to a boolean

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 four values - `ECSchemaName`, `ECClassName`, `ECPropertyName` and `ECPropertyType`.

`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`

`ECPropertyType` is case sensitive and corresponds to the data type of a `ECProperty` you want to select. Supported Type values are:

- `Boolean` - describes a logical value which is either true or false,
- `Number` - treated the same as Double,
- `Integer` - describes a whole number,
- `Double` - describes a real number,
- `String` - describes text.

### 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 four values - `ECSchemaName`, `ECClassName`, `ECPropertyName` and `ECPropertyType`.

`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`

`ECPropertyType` is case sensitive and corresponds to the data type of a `ECProperty` you want to select. Supported Type values are:

- `Boolean` - describes a logical value which is either true or false,
- `Number` - treated the same as Double,
- `Integer` - describes a whole number,
- `Double` - describes a real number,
- `String` - describes text.

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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
- `tonumber(var)` - returns the `var` value converted to a number

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)
- `indexof(str, searchValue [, start])` - returns the index of the first occurance in `str` at which a given string `searchValue` can be found in the array, or -1 if it is not present.
- `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`
- `tostring(var)` - returns the `var` value converted to a string

Supported boolean functions:

- `isin(var, var1[, var2[, ...]])` - returns `true` if `var` is equal to one of `var1, ...varN` else it returns `false`. `var, ...varN` must be of same type
- `toboolean(var)` - returns the `var` value converted to a boolean

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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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 four values - `ECSchemaName`, `ECClassName`, `ECPropertyName` and `ECPropertyType`.

`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`

`ECPropertyType` is case sensitive and corresponds to the data type of a `ECProperty` you want to select. Supported Type values are:

- `Boolean` - describes a logical value which is either true or false,
- `Number` - treated the same as Double,
- `Integer` - describes a whole number,
- `Double` - describes a real number,
- `String` - describes text.

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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.

### Extraction Triggers & Configuration

Mappings can be configured with `extractionEnabled` set to `true` or `false`. `true` means that Extractions will be automatically executed for the given Mapping when either a new ChangesetGroup is created (see [`ChangesetGroupCompletedEvent`](/apis/webhooks/#supportedevents)) or when the [Run Extraction](/apis/insights/operations/run-extraction/) operation is executed without the optional `mappings` parameter. **Note:** Multiple ChangesetGroups can be created for a single [Synchronization job](/apis/synchronization/) which will result in multiple automatic Extractions.

If `extractionEnabled` is set to `false`, all of the above mechanisms are disabled. However, Extractions can still be executed for a specific Mapping manually using the Run Extraction operation and the optional `mappings` parameter. To have better control over Extractions, it is recommended to set `extractionEnabled` to `false` and manually trigger Run Extraction when a Mapping's extracted data is stale and needs to be refreshed.

### 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.

### "Try it out" Limitations

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is 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 Aggregation. Each one links a Aggregation to a Report and each Report can have more than one Report Aggregation. 

### 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-aggregation

Created a new Report Aggregation successfully.

AggregationTableSet already exists in the 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.

---
