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.

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.

The soft quota of a stored item is 512 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.