GetArchiveValuesByTimeRange

Retrieve historical values of the Historian points within a specified time range.

Input Parameter

Item
Description
Request
GET
URL Parameter
  • request
    : JSON.
  • URL Parameter Members
    :
    • ServerName: String (required). The FactoryTalk Historian server name.
    • PointNames: Array in the string format (required). The point names to be queried in the Data Archive.
    • StartTime: Time in the string format (required). The start time of the time range.
    • EndTime: Time in the string format (required). The end time of the time range.
    • BoundaryType: String (optional). The rule of returning data values close to the boundary within the specified time range. Available inputs are Inside, Outside, and Interpolated. The default value is Inside.
    • FilterExpression: String (optional). The mathematical expressions to eliminate data for which the expressions evaluate as false. The default value is empty.
Request Header
Authentication
: String (required). Bearer Token string returned from the Login action.
Response-Format
 (optional): OPTIMIZE.
Request Body
None
Status Code
  • 200
    : The request succeeded.
  • 206
    : Partially processed.
  • 400
    : Bad request. For example, the URL parameter is not provided.
  • 401
    : Unauthorized.
  • 403
    : Forbidden.
  • 404
    : Resource not found.
  • 500
    : Internal server error.

Sample 1

Request Header
"Authorization": "eyJhbGciOiJIUzI1N…"
Request URL Parameter
request={"ServerName":"HisSrvName","PointNames":["TestPoint1","TestPoint2"],"StartTime":"*-8h","EndTime":"*"}
Response Body
{
	"Result": [{
			"Name": "TestPoint1",
			"Vqts": [{
				"Value": "500",
				"Quality": "Good",
				"Timestamp": "2024-03-21T02:18:23.4118499Z"
			}]
		},
		{
			"Name": "TestPoint2",
			"Vqts": [{
				"Value": "300",
				"Quality": "Good",
				"Timestamp": "2024-03-21T02:22:23.4118499Z"
			}]
		}
	],
	"Success": true,
	"ErrorMessage": ""
}
TIP:
  • StartTime and EndTime support fuzzy matching. In the previous example, the value "*-8h" in StartTime means that the start time is 8 hours ahead of the current time, and the value "*" in EndTime means that the end time is the current time.
  • The boundary type defines the rule that retrieves values close to the boundary within the specified time range. Available inputs are Inside, Outside, and Interpolated. If no type matches, it will use the default value of Inside.
    • Inside
      : Retrieves values at start and end times if they exist, or the closest values generated within the range.
    • Outside
      : Retrieves the closest values generated immediately outside the range.
    • Interpolated
      : Retrieves interpolated values at start and end times.

Sample 2

If the request header contains the response format of OPTIMIZE, the sample should be:
Request Header
"Authorization": "eyJhbGciOiJIUzI1N…"
"response-format": "optimize"
Request URL Parameter
request={"ServerName":"HisSrvName","PointNames":["TestPoint1","TestPoint2"],"StartTime":"2025-04-20T18:37:40.2606048Z","EndTime":"*"}
Response Body
{
	"Result": {
		"Names": [
			"TestPoint1",
			"TestPoint2"
		],
		"MaxCount": {
			"Name": "TestPoint2",
			"Count": 1
		},
		"Data": {
			"2025-04-20T18:37:40.2606048Z": [
				[
					"4096",
					"4096"
				]
			]
		}
	},
	"Success": true,
	"ErrorMessage": ""
}
TIP:
If names lack values at the time of retrieval, their values are displayed as empty.
Provide Feedback
Have questions or feedback about this documentation? Please submit your feedback here.
Normal