Request

Response

    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:

    1. Retrieve Hubs.
    2. Retrieve Projects.
    3. Retrieve Folders.
    4. Retrieve Items.

    You will use the following operations in this topic:

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

    1. 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
    2. In the Query Variables Pane, enter the modelId. To know how to obtain the modelId (tipRootModel), refer to Retrieve Items.

      Query Variables

      {
         "modelId": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E"
      }
      
    3. 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.

    1. 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
    2. In the Query Variables Pane, enter the modelId and the time window you want to query. Both startTime and endTime are 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"
      }
      
    3. 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.

    1. 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
    2. In the Query Variables Pane, enter the modelId and the timestamp at which you want to resolve the model.

      Query Variables

      {
         "modelId": "bW9kZWx-d00wSVJmdmczT1VLTHZsYjJ4dDJMdF9MMkN-Y3hTMXhkYkFmSjFZZWZUSldUQU9zUV9hZ2E",
         "time": "2026-04-15T12:00:00.000Z"
      }
      
    3. Click Play. The response returns the model’s state at the requested timestamp. The top-level timestamp echoes the time the model was resolved at, while each entry in history.results carries its own timestamp for 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.

    1. 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
    2. In the Query Variables Pane, enter the historyChangeId saved from Step 1.

      Query Variables

      {
         "historyChangeId": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ"
      }
      
    3. 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.

    1. 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
    2. In the Query Variables Pane, enter the historyChangeId and the new description.

      Query Variables

      {
         "input": {
            "historyChangeId": "aGlzdG9yeX5tdmVyc2lvbi1jcmVhdGVkLTAwMQ",
            "description": "Released for production review"
         }
      }
      
    3. 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 history field is also exposed on DesignItem, ConfiguredDesignItem, DrawingItem, and BasicItem. The query shape and arguments are the same as on Model.
    • Subtype-specific fields: Each entry returned by history resolves to a concrete subtype of HistoryChange. Use __typename together 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 time argument resolves an entity at a point in time, see Time Based History.