Track Object History
This topic provides instructions on how to retrieve the change history of an object using time-based history in the Manufacturing Data Model API. You will learn how to:
- Fetch the most recent history changes for a model
- Filter history by change type and time range
- Resolve a model as it existed at a specific point in time
- Fetch a single history change by its ID
- Update the description of an existing history change
As a prerequisite for completing the current topic, you need to complete the following tasks:
You will use the following operations in this topic:
| Type | Operation | Description |
|---|---|---|
| Query | model | Retrieves a model and its history at an optional point in time. |
| Query | historyChange | Retrieves a single history change by its ID. |
| Mutation | updateHistoryChangeDescription | Updates the description of an existing history change. |
Step 1 - Retrieve Recent History Changes for a Model
The model query exposes a history field that returns a paginated list of history changes for the model. Without any filters, the most recent changes are returned in reverse chronological order.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query GetModelHistory($modelId: ID!) { model(modelId: $modelId) { id history(pagination: { limit: 25 }) { pagination { cursor } results { __typename id timestamp description author { id name } } } } }Show More - In the Query Variables Pane, enter the
modelId. To know how to obtain themodelId(tipRootModel), refer to Retrieve Items.Query Variables
{ "modelId": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E" } - Click Play. The response lists the most recent changes on the model, each tagged with its concrete subtype via
__typename.Response
{ "data": { "model": { "id": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E", "history": { "pagination": { "cursor": null }, "results": [ { "__typename": "VersionCreatedHistoryChange", "id": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ", "timestamp": "2026-04-20T10:15:30.000Z", "description": "Design review update", "author": { "id": "ABCDE12345FGHIJ", "name": "Jane Doe" } }, { "__typename": "PropertiesUpdatedHistoryChange", "id": "aGlzdG9yeX5wcm9wZXJ0aWVzLXVwZGF0ZWQtMDAy", "timestamp": "2026-04-19T16:42:11.000Z", "description": null, "author": { "id": "FGHIJ67890KLMNO", "name": "John Smith" } } ] } } } }Show More
Note: Save one of the results.id values from this response. You will need it in Step 4 and Step 5. The __typename field reports the concrete subtype of each change; you will use it in Step 2 to read subtype-specific fields.
Step 2 - Filter by Change Type and Time Range
The history field accepts a HistoryInput argument that lets you narrow results by change type and by a start/end time. Use filterTypes to select specific values from HistoryChangeTypeEnum, and use inline fragments (... on TypeName) to read fields that are specific to a subtype.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query GetFilteredHistory( $modelId: ID! $startTime: DateTime $endTime: DateTime ) { model(modelId: $modelId) { id history( input: { startTime: $startTime endTime: $endTime filterTypes: [PROPERTY_UPDATED, COMPONENT_PART_NUMBER_UPDATED, VERSION_CREATED] } pagination: { limit: 50 } ) { pagination { cursor } results { __typename id timestamp author { id name } ... on PropertiesUpdatedHistoryChange { properties { definition { name } value } } ... on ComponentPartNumberHistoryChange { partNumber { value } } ... on VersionCreatedHistoryChange { version { id } } } } } }Show More - In the Query Variables Pane, enter the
modelIdand the time window you want to query. BothstartTimeandendTimeare optional. Omit either to extend the range to the beginning or the most recent change, respectively.Query Variables
{ "modelId": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E", "startTime": "2026-04-01T00:00:00.000Z", "endTime": "2026-04-30T23:59:59.000Z" } - Click Play. The response includes only the change types you specified, and each entry exposes the subtype-specific fields requested via inline fragments.
Response
{ "data": { "model": { "id": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E", "history": { "pagination": { "cursor": null }, "results": [ { "__typename": "PropertiesUpdatedHistoryChange", "id": "aGlzdG9yeX5wcm9wZXJ0aWVzLXVwZGF0ZWQtMDAy", "timestamp": "2026-04-19T16:42:11.000Z", "author": { "id": "FGHIJ67890KLMNO", "name": "John Smith" }, "properties": [ { "definition": { "name": "Material Name" }, "value": "Steel" } ] }, { "__typename": "ComponentPartNumberHistoryChange", "id": "aGlzdG9yeX5wYXJ0LW51bWJlci0wMDM", "timestamp": "2026-04-15T09:08:00.000Z", "author": { "id": "ABCDE12345FGHIJ", "name": "Jane Doe" }, "partNumber": { "value": "ESP-001" } } ] } } } }Show More
Note: Use the cursor returned in pagination to fetch the next page of results. Pass it back as pagination: { cursor: "..." } on the next call.
Step 3 - Resolve a Model at a Specific Point in Time
The model query accepts an optional time argument. When provided, the model and everything reachable through it are resolved to their state at that timestamp. This is useful for reconstructing what a design looked like before a particular change.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query GetModelAtTime($modelId: ID!, $time: DateTime) { model(modelId: $modelId, time: $time) { id timestamp name { value } materialName { value } history(pagination: { limit: 10 }) { results { __typename id description timestamp author { id name } } } } }Show More - In the Query Variables Pane, enter the
modelIdand the timestamp at which you want to resolve the model.Query Variables
{ "modelId": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E", "time": "2026-04-15T12:00:00.000Z" } - Click Play. The response returns the model’s state at the requested timestamp. The top-level
timestampechoes the time the model was resolved at, while each entry inhistory.resultscarries its owntimestampfor when that specific change occurred.Response
{ "data": { "model": { "id": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E", "timestamp": "2026-04-15T12:00:00.000Z", "name": { "value": "Espresso Machine" }, "materialName": { "value": "Aluminum" }, "history": { "results": [ { "__typename": "PropertiesUpdatedHistoryChange", "id": "aGlzdG9yeX5wcm9wZXJ0aWVzLXVwZGF0ZWQtMDA0", "description": "Switched material from Aluminum to Steel", "timestamp": "2026-04-15T11:50:00.000Z", "author": { "id": "ABCDE12345FGHIJ", "name": "Jane Doe" } } ] } } } }Show More
Note: Model.timestamp reports the resolution time (the time you supplied, or the current time if it was omitted) rather than the model’s last-modified time.
Step 4 - Fetch a Single History Change by ID (Optional)
When you already have a history change ID (for example, from an event payload received over PubNub or from a previous query), you can fetch that change directly without traversing the parent object.
- In Manufacturing Data Model Explorer, enter the following query in the Query Pane:
Query
query GetHistoryChange($historyChangeId: ID!) { historyChange(historyChangeId: $historyChangeId) { __typename id timestamp description author { id name } } }Show More - In the Query Variables Pane, enter the
historyChangeIdsaved from Step 1.Query Variables
{ "historyChangeId": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ" } - Click Play. The response returns the single history change identified by the ID.
Response
{ "data": { "historyChange": { "__typename": "VersionCreatedHistoryChange", "id": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ", "timestamp": "2026-04-20T10:15:30.000Z", "description": "Design review update", "author": { "id": "ABCDE12345FGHIJ", "name": "Jane Doe" } } } }Show More
Step 5 - Update a History Change Description (Optional)
Use the updateHistoryChangeDescription mutation to add or revise the description on an existing history change, for example to record the reason for a part-number change.
- In Manufacturing Data Model Explorer, enter the following mutation in the Query Pane:
Mutation
mutation UpdateHistoryChangeDescription($input: UpdateHistoryChangeDescriptionInput!) { updateHistoryChangeDescription(input: $input) { historyChange { id description timestamp } } }Show More - In the Query Variables Pane, enter the
historyChangeIdand the newdescription.Query Variables
{ "input": { "historyChangeId": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ", "description": "Released for production review" } } - Click Play. The response confirms the updated description on the history change.
Response
{ "data": { "updateHistoryChangeDescription": { "historyChange": { "id": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ", "description": "Released for production review", "timestamp": "2026-04-20T10:15:30.000Z" } } } }Show More
Additional Notes
- Other entities support history: The
historyfield is also exposed onDesignItem,ConfiguredDesignItem,DrawingItem, andBasicItem. The query shape and arguments are the same as onModel. - Subtype-specific fields: Each entry returned by
historyresolves to a concrete subtype of HistoryChange. Use__typenametogether with inline fragments (... on TypeName) to read fields that are specific to a subtype. - Filter values: For the full list of values you can pass in
filterTypes, see HistoryChangeTypeEnum. - Conceptual reference: For more background on time-based history and how the
timeargument resolves an entity at a point in time, see Time Based History.