# Get Ledger Entry History

This endpoint retrieves the historical values of Ledger Entries with corresponding Unix epoch timestamps (opens new window). The timestamps denote when the Entry values from the given Ledger were updated.

How long the history is stored is defined in the given Ledger Entry through the "history" attribute in the add_twin_ledger_entry endpoint. If the value of the "history" attribute is null, the time period is defined as INF (infinite). The limit of stored historical values of an Entry is 1000. If there are more than 1000 Entry value changes within the specified time period, only 1000 most recent Entry values will be stored. If there is no "history" attribute, the history service is not enabled and historical Entry values are not stored. The soft quota of a stored item is 128 bytes. The value of the "history" attribute must match the regular expression (opens new window) ^([1-9][0-9]{0,2}[DWMY])|(INF)$.

Method Path Operation*
GET /twins/{twin}/ledgers/personal/history get_twin_ledger_entry_history
GET /twins/{twin}/ledgers/owner/history get_twin_ledger_entry_history
GET /twins/{twin}/ledgers/{ledger}/history get_twin_ledger_entry_history

*

In order for a user to perform the "get_twin_ledger_entry_history" operation, the "get_twin_ledger_entry_history" permission must be included in the list of allowed actions in the statement of the user's role.

# Request

Parameter Type In Description
{twin}
required
string path Twin UUID.
{ledger}
required *
string path Ledger UUID.
ge
optional **
timestamp query string Returns Entries where update time is greater than or equal to the given Unix (opens new window) timestamp.
le
optional **
timestamp query string Returns Entries where update time is lower than or equal to the given Unix (opens new window) timestamp.
limit
optional **
integer, DEFAULT=100 query string Limit on the number of Entry values to be returned in descending order. The default and maximum value is 100.
entries
optional ***
string query string Keys of the Entries to be returned in the response.

*

This parameter is required if the history we request to retrieve is not set to personal or owner in the path of the request, but is based on the Ledger UUID.

**

The ge, le, limit, and entries parameters are optional and do not need to be included in the request. If they are not included in the request, their default values are used. If the number of the records to be returned exceeds the limit provided in the request:

  • if the ge parameter is provided, the records to be returned are counted starting from the timestamp provided.
  • if the le parameter is provided, the records to be returned are counted from the timestamp provided.
  • if both ge and le parameters are provided, the records to be returned are counted from the timestamp provided in the le parameter (.i.e., the most recent records are returned).

***

If no Entry keys are specified, all Entries will be returned in the response filtered by the "ge", "le", and/or "limit" parameters (if these parameters have been included in the query string).

# Response

The response returns a list of Entries with the history of Entry value changes in form of key-value pairs.

Attribute Type Description
entries dictionary Key-value pairs:
- Key: Time when the Entry value was changed
- Value: Entry value.

# Status codes

Requests to this endpoint result in generic status codes. For a comprehensive list of status codes, please consult the Status Codes section.