Access iModels data using OData v4 interface

imodels-odata

## iModels OData

Access iModel data using an OData interface.

### Mapping

The iModels OData API allows accessing iModels data in the view of Reporting API [Mappings](/apis/insights/overview/) without running the [Extraction](/apis/insights/operations/run-extraction/) process.

Note: Not all Mapping configuration options are supported in this API.

### Use cases

This API should be used in embedded views where only partial data is fetched. Follow the [Customizing the iTwin Viewer](/tutorials/itwin-viewer-hello-world/) tutorial on how to integrate it into iTwin Viewer.

Use the Reporting API [Extraction](/apis/insights/operations/run-extraction/) process for full data exports.

### OData

OData APIs can be used with tools and libraries that support [OData v4 protocol](https://www.odata.org/documentation/) and [OAUTH2 Authorization](/apis/overview/authorization/).

## Client Packages

To read the OData endpoint [OData Library](https://www.odata.org/libraries/) is needed.

## Media Links

Additional information can be found here:

* Creating and Sharing Insights with the iTwin platform - [YouTube](https://www.youtube.com/watch?v=6MhEm6cTOqY)
* Decluttering your Digital Twin - [Medium](https://medium.com/itwinjs/decluttering-your-digital-twin-9000bd017f50)

---

Retrieves all Groups (OData Entities) of an iModel Mapping. This endpoint can be used as an OData feed.

iModel Mappings can be managed using [Reporting API](/apis/insights/).

### Mapping Support

Direct data query using iModel [Mapping](/apis/insights/overview/) supports a subset of available [Mapping](/apis/insights/overview/) configuration options. Unsupported properties will be excluded from results.

Supported iModel Mapping configurations options:
- [Group](/apis/insights/operations/create-group/) - All query types supported
- [GroupProperty](/apis/insights/operations/create-groupproperty/) - All property selection supported
- [CalculatedProperty](/apis/insights/operations/create-calculatedproperty/) - All calculations are supported
- [CustomCalculation](/apis/insights/operations/create-customcalculation/) - All operators supported

### Notes

This is an OData v4 compliant endpoint.

This endpoint should only be accessed using OData compliant libraries and tools.

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 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 `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the Project level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the Project level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project the iModel belongs to.

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.

---


mapping-odata

imodelId

changesetId

mappingId

OAuth access token with `itwin-platform` scope

Authorization

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

Accept

Retrieved OData feed for a given iModel successfully.

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

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

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

retry-after

---

Lists the data for a Group and selected Properties.

iModel Mappings can be managed using [Reporting API](/apis/insights/).

### Mapping Support

Direct data query using iModel [Mapping](/apis/insights/overview/) supports a subset of available [Mapping](/apis/insights/overview/) configuration options. Unsupported properties will be excluded from results.

Supported iModel Mapping configurations options:
- [Group](/apis/insights/operations/create-group/) - All query types supported
- [GroupProperty](/apis/insights/operations/create-groupproperty/) - All property selection supported
- [CalculatedProperty](/apis/insights/operations/create-calculatedproperty/) - All calculations are supported
- [CustomCalculation](/apis/insights/operations/create-customcalculation/) - All operators supported

### Notes

This is an OData v4 compliant endpoint.

This endpoint should only be accessed using OData compliant libraries and tools.

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 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 `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the Project level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the Project level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project the iModel belongs to.

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.

---


mapping-odata-entity

groupName

The $top query option requests the number of items in the queried collection to be included in the result.

$top

The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result.

$skip

The $select query option requests a specific set of properties for each entity.
The value of $select is a comma separated list of property names to select. All properties are selected if it is not set or set to `*`.

$select

The $filter query option requests a specific set of entities.
The given filter is evaluated for each entity and only entities where the filter evaluates to true are returned.
Properties supported for filtering: `ECInstanceId`, `ECClassId`.
Supported operators: `eq`, `lt`, `le`, `gt`, `ge`, `ne`, `in`, `and`, `or`.
Parenthesis `(` and `)` can be used to change the precedence of operations.
Examples of $filter values:
`$filter=ECInstanceId eq 0x123`
`$filter=ECInstanceId in (0x123, 0x234, 0x345)`
`$filter=ECInstanceId gt 0x1 and ECInstanceId lt 0x5`
`$filter=ECInstanceId eq 0x123 or ECInstanceId eq 0x456`
`$filter=ECClassId eq 0x5`
`$filter=ECClassId eq 'BisCore.GeometricElement3d'`

$filter

Retrieved specified OData Entity successfully.

---

Retrieves Definitions of an iModel Mapping.

iModel Mappings can be managed using [Reporting API](/apis/insights/).

### Mapping Support

Direct data query using iModel [Mapping](/apis/insights/overview/) supports a subset of available [Mapping](/apis/insights/overview/) configuration options. Unsupported properties will be excluded from results.

Supported iModel Mapping configurations options:
- [Group](/apis/insights/operations/create-group/) - All query types supported
- [GroupProperty](/apis/insights/operations/create-groupproperty/) - All property selection supported
- [CalculatedProperty](/apis/insights/operations/create-calculatedproperty/) - All calculations are supported
- [CustomCalculation](/apis/insights/operations/create-customcalculation/) - All operators supported

### Notes

This is an OData v4 compliant endpoint.

This endpoint should only be accessed using OData compliant libraries and tools.

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 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 `imodels_webview` permission assigned at the iModel level and at least `imodels_webview` permission assigned at the Project level. If permissions at the iModel level are not configured, then user must have `imodels_webview` permission assigned at the Project level.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project the iModel belongs to.

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.

---


mapping-odata-metadata

Retrieved iModel OData metadata successfully.