Named Groups define subsets of iModel data for downstream applications like clash detection or carbon analysis.

named-groups

# Named Groups API

Named Groups define subsets of iModel data for downstream applications like Clash Detection or Carbon Analysis. They are scoped at an iTwin and applicable to any iModels storing the same business objects or schema. An example might include selections for materials like concrete and steel when defining Environmental Product Declarations (EPD) workflows. Named Groups can be defined for a specific purpose or shared across workflows. For example, a Named Group defined for the EPD workflow might also apply to generating procurement reports.

ngv1-mindaugas

---

Creates a group. A group is a collection of design elements from an iModel represented by an [ECSQL](https://www.itwinjs.org/learning/ecsql/) query.

### Group Query

The `query` parameter of a Group must be a valid ECSQL query.

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`. However, it is recommended to always select at least `ECInstanceId` and `ECClassId` columns.

- `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, ECClassId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId, ECClassId 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 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 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 Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases the provided ECSQL query is required to select `ECInstanceId` and `ECClassId`. If `ECClassId` is omitted, the service assumes that query selects elements from the `bis.Element` class or its descendants. In some cases the results might be unexpected, e.g., you assume that you are querying `bis.ElementAspect` but you only select `ECInstanceId` so the service only selects the elements that have a matching `ECInstanceId`. Because of this it is always recommended to select both `ECInstanceId` and `ECClassId`.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwin-platform`.

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 iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin 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://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) 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-group

OAuth access token with `itwin-platform` scope

Authorization

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

Accept

default

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

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

InvalidApplicationTier

User is not authorized to create a Group.

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)

MissingDisplayName

MissingQuery

InvalidDisplayName

DuplicateMetadataKey

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

---

Deletes a group.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwin-platform`.

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 iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin 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://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) 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-group

groupId

User is not authorized to delete a Group.

---

Retrieves a group.

### Group Query

The `query` parameter of a Group must be a valid ECSQL query.

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`. However, it is recommended to always select at least `ECInstanceId` and `ECClassId` columns.

- `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, ECClassId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId, ECClassId 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 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 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 Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases the provided ECSQL query is required to select `ECInstanceId` and `ECClassId`. If `ECClassId` is omitted, the service assumes that query selects elements from the `bis.Element` class or its descendants. In some cases the results might be unexpected, e.g., you assume that you are querying `bis.ElementAspect` but you only select `ECInstanceId` so the service only selects the elements that have a matching `ECInstanceId`. Because of this it is always recommended to select both `ECInstanceId` and `ECClassId`.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_view` permission(s) assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin 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://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) 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 groups of an iTwin.

### Notes

The `Prefer` header can be used to specify how much result metadata is desired by the client. The `Prefer` request header field is used to indicate that particular server behaviors are preferred by the client but are not required for successful completion of the request.

This operation supports `"return=representation"` and `"return=minimal"` preferences.

The `"return=representation"` preference indicates that the client prefers that the server include an entity representing the current state of the resource in the response to a successful request.
The `"return=minimal"` preference indicates that the client wishes the server to return only a minimal response to a successful request. This is the default preference if `Prefer` header is not specified.

### Group Query

The `query` parameter of a Group must be a valid ECSQL query.

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`. However, it is recommended to always select at least `ECInstanceId` and `ECClassId` columns.

- `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, ECClassId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId, ECClassId 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 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 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 Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases the provided ECSQL query is required to select `ECInstanceId` and `ECClassId`. If `ECClassId` is omitted, the service assumes that query selects elements from the `bis.Element` class or its descendants. In some cases the results might be unexpected, e.g., you assume that you are querying `bis.ElementAspect` but you only select `ECInstanceId` so the service only selects the elements that have a matching `ECInstanceId`. Because of this it is always recommended to select both `ECInstanceId` and `ECClassId`.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwin-platform`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

### Authorization

User must have `insights_view` permission(s) assigned at the iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin 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://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) 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-itwin-groups

iTwinId

Optional max items to be sent in response.

$top

Optional token to retrieve next page in paginated response.

$continuationToken

Indicates a level of details in the response. This operation supports 'return=representation' and 'return=minimal' preferences.

Prefer

Minimal

Representation

MultipleTop

EmptyTop

InvalidTop

TopOutOfRange

MultipleContinuationTokens

---

Updates a group.

### Group Query

The `query` parameter of a Group must be a valid ECSQL query.

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`. However, it is recommended to always select at least `ECInstanceId` and `ECClassId` columns.

- `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, ECClassId FROM bis.Element` is a valid query
- Assuming that class `Building.Beam` is a descendant of the class `bis.Element`, the query `SELECT ECInstanceId, ECClassId 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 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 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 Element.id ECInstanceId FROM Building.BeamAspect` is valid

In all other cases the provided ECSQL query is required to select `ECInstanceId` and `ECClassId`. If `ECClassId` is omitted, the service assumes that query selects elements from the `bis.Element` class or its descendants. In some cases the results might be unexpected, e.g., you assume that you are querying `bis.ElementAspect` but you only select `ECInstanceId` so the service only selects the elements that have a matching `ECInstanceId`. Because of this it is always recommended to select both `ECInstanceId` and `ECClassId`.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `itwin-platform`.

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 iTwin level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given iTwin 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://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) 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.

---
