---
title: "POST /workspaces/{workspaceId}/entity-properties/history"
method: POST
path: "/workspaces/{workspaceId}/entity-properties/history"
---

# POST /workspaces/{workspaceId}/entity-properties/history

`POST /workspaces/{workspaceId}/entity-properties/history`

Retrieves information about the history of a time series property value for a component, component type, entity, or workspace.

You must specify a value for `workspaceId`. For entity-specific queries, specify values for `componentName` and `entityId`. For cross-entity quries, specify a value for `componentTypeId`.

## Path parameters

- `workspaceId` string, required

## Request body

- object
  - `entityId` string — The ID of the entity.
  - `componentName` string — The name of the component.
  - `componentPath` string — This string specifies the path to the composite component, starting from the top-level component.
  - `componentTypeId` string — The ID of the component type.
  - `selectedProperties` String[], required — A list of properties whose value histories the request retrieves.
  - `propertyFilters` PropertyFilter[] — A list of objects that filter the property value history request.
    - `propertyName` string — The property name associated with this property filter.
    - `operator` string — The operator associated with this property filter.
    - `value` object — The value associated with this property filter.
      - `booleanValue` boolean — A Boolean value.
      - `doubleValue` number, double — A double value.
      - `integerValue` integer — An integer value.
      - `longValue` integer — A long value.
      - `stringValue` string — A string value.
      - `listValue` DataValue[] — A list of multiple values.
        - `booleanValue` boolean — A Boolean value.
        - `doubleValue` number, double — A double value.
        - `integerValue` integer — An integer value.
        - `longValue` integer — A long value.
        - `stringValue` string — A string value.
        - `listValue` DataValue[] — A list of multiple values.
        - `mapValue` object — An object that maps strings to multiple <code>DataValue</code> objects.
        - `relationshipValue` object — A value that relates a component to another component.
          - `targetEntityId` string — The ID of the target entity associated with this relationship value.
          - `targetComponentName` string — The name of the target component associated with the relationship value.
        - `expression` string — An expression that produces the value.
      - `mapValue` object — An object that maps strings to multiple <code>DataValue</code> objects.
      - `relationshipValue` object — A value that relates a component to another component.
        - `targetEntityId` string — The ID of the target entity associated with this relationship value.
        - `targetComponentName` string — The name of the target component associated with the relationship value.
      - `expression` string — An expression that produces the value.
  - `startDateTime` string, date-time — supports epoch seconds value
  - `endDateTime` string, date-time — supports epoch seconds value
  - `interpolation` object — An object that specifies how to interpolate data in a list.
    - `interpolationType` 'LINEAR' — The interpolation type.
    - `intervalInSeconds` integer — The interpolation time interval in seconds.
  - `nextToken` string — The string that specifies the next page of results.
  - `maxResults` integer — <p>The maximum number of results to return at one time. The default is 25.</p> <p>Valid Range: Minimum value of 1. Maximum value of 250.</p>
  - `orderByTime` 'ASCENDING' | 'DESCENDING' — The time direction to use in the result order.
  - `startTime` string — Timestamp represented in ISO 8601 format
  - `endTime` string — Timestamp represented in ISO 8601 format

## Response `200`

Success

- GetPropertyValueHistoryResponse
  - `propertyValues` PropertyValueHistory[], required — An object that maps strings to the property definitions in the component type. Each string in the mapping must be unique to this object.
    - `entityPropertyReference` object, required — An object that uniquely identifies an entity property.
      - `componentName` string — The name of the component.
      - `componentPath` string — This string specifies the path to the composite component, starting from the top-level component.
      - `externalIdProperty` object — A mapping of external IDs to property names. External IDs uniquely identify properties from external data stores.
      - `entityId` string — The ID of the entity.
      - `propertyName` string, required — The name of the property.
    - `values` PropertyValue[] — A list of objects that contain information about the values in the history of a time series property.
      - `timestamp` string, date-time — The timestamp of a value for a time series property.This field is deprecated and will throw an error in the future. Use time instead.
      - `value` object, required — An object that specifies a value for a time series property.
        - `booleanValue` boolean — A Boolean value.
        - `doubleValue` number, double — A double value.
        - `integerValue` integer — An integer value.
        - `longValue` integer — A long value.
        - `stringValue` string — A string value.
        - `listValue` DataValue[] — A list of multiple values.
          - `booleanValue` boolean — A Boolean value.
          - `doubleValue` number, double — A double value.
          - `integerValue` integer — An integer value.
          - `longValue` integer — A long value.
          - `stringValue` string — A string value.
          - `listValue` DataValue[] — A list of multiple values.
          - `mapValue` object — An object that maps strings to multiple <code>DataValue</code> objects.
          - `relationshipValue` object — A value that relates a component to another component.
            - `targetEntityId` string — The ID of the target entity associated with this relationship value.
            - `targetComponentName` string — The name of the target component associated with the relationship value.
          - `expression` string — An expression that produces the value.
        - `mapValue` object — An object that maps strings to multiple <code>DataValue</code> objects.
        - `relationshipValue` object — A value that relates a component to another component.
          - `targetEntityId` string — The ID of the target entity associated with this relationship value.
          - `targetComponentName` string — The name of the target component associated with the relationship value.
        - `expression` string — An expression that produces the value.
      - `time` string — <p>ISO8601 DateTime of a value for a time series property.</p> <p>The time for when the property value was recorded in ISO 8601 format: <i>YYYY-MM-DDThh:mm:ss[.SSSSSSSSS][Z/±HH:mm]</i>.</p> <ul> <li> <p> <i>[YYYY]</i>: year</p> </li> <li> <p> <i>[MM]</i>: month</p> </li> <li> <p> <i>[DD]</i>: day</p> </li> <li> <p> <i>[hh]</i>: hour</p> </li> <li> <p> <i>[mm]</i>: minute</p> </li> <li> <p> <i>[ss]</i>: seconds</p> </li> <li> <p> <i>[.SSSSSSSSS]</i>: additional precision, where precedence is maintained. For example: [.573123] is equal to 573123000 nanoseconds.</p> </li> <li> <p> <i>Z</i>: default timezone UTC</p> </li> <li> <p> <i>± HH:mm</i>: time zone offset in Hours and Minutes.</p> </li> </ul> <p> <i>Required sub-fields</i>: YYYY-MM-DDThh:mm:ss and [Z/±HH:mm]</p>
  - `nextToken` string — The string that specifies the next page of results.

## Other responses

- `480` — InternalServerException
- `481` — ConnectorFailureException
- `482` — AccessDeniedException
- `483` — ResourceNotFoundException
- `484` — ThrottlingException
- `485` — ValidationException
- `486` — ConnectorTimeoutException

---

[API](https://skmtc.net/aws/apis/iottwinmaker.md) · [All operations](https://skmtc.net/aws/apis/iottwinmaker/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/iottwinmaker/versions/a66a26fd65ea/schema)