Fix StateTime in GE Proficy Historian REST API: send calculationParameters (mode 14) and check version support

Learn why StateTime requests return zero in GE Proficy Historian REST API and how to fix: pass calculationParameters (target state) and verify version support.

When you try to query the GE Proficy Historian Calculated REST API for StateTime, the documentation shows the calculation option but doesn’t clearly state which parameter carries the state value you want to evaluate. The result is a seemingly correct request that returns an unhelpful zero.

Problem setup

The goal is to calculate how long a given tag stayed at a specific value over a time range. The request goes to the calculated datapoints endpoint with calculationMode set to StateTime (14), but without a clear way to tell the API which state to measure.

endpoint = "https://<server_name>:8443/historian-rest-api/v1/datapoints/calculated"
query_args = {
    "tagNames": "TagName",
    "start": "2025-04-17T19:00:00-04:00",
    "end": "2025-04-17T23:00:00-04:00",
    "samplingMode": 6,
    "calculationMode": 14,
    "direction": 0,
    "count": 1,
    "intervalMs": 100000,
}
resp = requests.get(endpoint, headers=headers, params=query_args, verify=False)
if resp.ok:
    print(resp.json())
else:
    print(resp.status_code, resp.text)

What’s actually missing

For StateTime (calculationMode 14), the API expects the target state to be provided via the calculationParameters field. That value is the exact state the server should measure over the requested interval. For example, to compute the time a tag was equal to 1, you pass calculationParameters with the value "1".

There’s an additional caveat. Vendor confirmation states that StateTime and StateCount were removed from the newer versions of the Proficy REST API, while references to them remained in the documentation. If you are on one of those newer builds, the request won’t produce the expected numbers even if you supply calculationParameters.

How to call StateTime when it is available

If your deployment still exposes StateTime through the REST API, include calculationParameters and set it to the state you want to evaluate. Everything else in the request can remain as is.

endpoint = "https://<server_name>:8443/historian-rest-api/v1/datapoints/calculated"
query_args = {
    "tagNames": "TagName",
    "start": "2025-04-17T19:00:00-04:00",
    "end": "2025-04-17T23:00:00-04:00",
    "samplingMode": 6,
    "calculationMode": 14,
    "direction": 0,
    "count": 1,
    "intervalMs": 100000,
    "calculationParameters": "1"
}
resp = requests.get(endpoint, headers=headers, params=query_args, verify=False)
if resp.ok:
    print(resp.json())
else:
    print(resp.status_code, resp.text)

Why this matters

Two details decide whether you’ll get a meaningful result. First, StateTime requires calculationParameters to define the state being measured; without it, you can see zeros despite a correct endpoint and mode. Second, some releases of the REST API no longer implement StateTime and StateCount even though they are still shown in the docs, which can send you debugging in the wrong direction.

Takeaways

If your API version supports StateTime (mode 14), pass calculationParameters with the state value you want to compute. If your instance is on a newer build where StateTime/StateCount were removed from the REST API, those calculations won’t be available through this endpoint. Knowing both the required parameter and the feature’s availability by version saves time and prevents chasing ghosts in configuration or data.