# Changed Elements

The Changed Elements API provides consumers with the elements that have changed in an iModel between two changesets. This API has four operations:

1. Enable Change Tracking
2. Get Change Tracking
3. Get Comparison
4. Get Changesets

Before obtaining a comparison, it is necessary to enable change tracking of an iModel. This means that the API will be listening to the following events:
1. New Named Version Created
2. Changeset Group Completed

When any of those events trigger, the API will process the new changes and store a summary of all the elements that have changed.

After tracking is enabled and the iModel is processed, the comparison endpoint may be used to query for a summary of changed elements between any two given `ChangeSets`.

changed-elements

enable-tracking-body

enable

boolean

iModelId

string

iTwinId

Contains error information and an optional array of more specific errors.

Error

One of a server-defined set of error codes.

code

A human-readable representation of the error.

message

target

details

ErrorDetails

Error Details

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

ErrorResponse

error

Error Response

---

Enables or disables change tracking for an iModel. This operation requires you to pass the enable value, iModel Id and project Id in the body of the request as a JSON object.

Once enabled, when creating a new named version of an iModel, or when a changeset group completes, the changesets are processed to find all changed elements. You can then request this data using the `GET /comparison` operation.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `changedelements:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

enable-change-tracking

The body should contain a JSON object with the enable value, iModel Id and project Id.

OAuth access token with scope `changedelements:modify`

Authorization

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

Accept

Change tracking for iModel was updated 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.

application/json;InvalidAuthorizationScheme

The user has insufficient permissions for the requested operation.

This response indicates that disabling change tracking is not possible because the iModel is not valid.

A URL parameter was malformed or the body of the request is invalid.

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

---

Get a list of processing statuses for changesets in an iModel. This list allows you to inspect which changesets are ready to be used to generate a comparison summary.

---

get-changesets

Amount of changesets to return in a single result. Optional.

$top

Amount of changesets to skip when returning results. Optional.

$skip

Id of the iTwin where the iModel resides.

Id of the iModel to query for status of changesets.

OAuth access token with scope `changedelements:read`

This response indicates that provided iTwin or iModel was not found.

This response indicates that a URL parameter was malformed or there are missing required parameters.

---

Obtains which elements have changed in the iModel between the given start and end changesets.

This information will only be available after change tracking has been enabled and the processing operation completes.

### Understanding Change

The comparison returns a [ChangedElements](https://www.itwinjs.org/reference/core-common/entities/changedelements/) object. This interface contains different arrays of the same size. Each element is specified by a single index in all arrays. Some of the relevant arrays to understand what changes occurred to an element are listed below:

**opcodes**: Contains the operation codes that tells us if the element was inserted, updated, or deleted in the change. See [DbOpcode](https://www.itwinjs.org/reference/core-bentley/besqlite/dbopcode/) for more information. The appropriate values are listed below:

| Opcode | Description |
|:------:|-----------|
| 9 | Element was deleted |
| 23 | Element was modified |
| 18 | Element was inserted |

&nbsp;
&nbsp;

**type**: Contains the type of change that occurred to the element. This number is a bit-flag and can be used to know whether the element had property changes, geometric changes, placement changes, indirect changes, and hidden property changes. See [TypeOfChange](https://www.itwinjs.org/reference/core-common/entities/typeofchange/) for more information. Below is a table with the values and their meaning:

| Type | Value | Description |
|------|:-----:|-------------|
| Property | 1 | A property in the element changed |
| Geometry | 2 | The geometry of the element changed |
| Placement | 4 | The placement of the element changed. This means that the element changed its volume, origin or rotation. |
| Indirect | 8 | Indirect change occurred to this element by a related instance that provides properties for it |
| Hidden | 16 | Hidden properties of the element changed |

### Authentication

Requires `Authorization` header with valid Bearer token for scope `changedelements:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-comparison

[Deprecated] Id of the iTwin the iModel resides in.

projectId

Changeset Id for the beginning of the comparison range.

startChangesetId

Changeset Id for the ending of the comparison range.

endChangesetId

This response indicates that provided comparison results are not ready or unexistent.

A URL parameter was malformed or there are missing required parameters.

---

Get tracking information about an iModel.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `changedelements:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---

get-tracking

Id of the iModel to query tracking information.

Enable Change Tracking - Changed Elements | iTwin Platform

This tutorial will teach you how to use the Changed Elements API to visualize change in your iTwin Application

Changed Elements

Authentication

Request

Request headers

Request body

Example

Response

Response 202 Accepted

Response 401 Unauthorized

Response 403 Forbidden

Response 404 Not Found

Response 422 Unprocessable Entity

Response 429 Too many requests

Definitions

enable-tracking-body

Error

Error Details

Error Response