Skip to main content
Examples use externalId for asset-centric projects. For data modeling, use instanceId instead. See Time series and datapoints for details.
Status codes are used to determine the quality of time series data points. The status code impacts data retrieval, aggregate compuation, and how the time series should be visualized. The implementation follows the OPC UA standard, and both the Cognite OPC UA and PI extractors support this feature. By default, the time series API only includes data points where the status code is Good and disregards other data points. To include data points with other status codes, you must pass additional parameters to the API.

​
Main status codes

All status codes fall into one of the main categories: Good, Uncertain, or Bad. If status code is missing, it is assumed to be Good (with code = 0). The API uses decimal numbers to represent status codes, but we have included the hexadecimal representation for reference.

​
Good

Good status codes are the default, and indicate that the data point is valid. If status code is missing, it is assumed to be Good with code = 0.

​
Bad

Bad status codes are by default omitted from the responses, and indicate that the value cannot be trusted.

​
Uncertain

Uncertain status codes may be treated as Bad (default) or Good, depending on the user.

​
Status code structure

A status code consists of a 32-bit unsigned integer code, and a string symbolic representation. A permitted status code consists of a category and a set of modifier flags or info flags. Use the category as is, or combine it with the modifier flags to get the full status code. To obtain the full numeric code, you add (or bitwise OR) the values for the category and the modifier flags. To obtain the full symbolic representation, you concatenate the representations for the category and the modifier flags. The code fields can be added together, while the representations can be concatenated, starting with the category and then the modifiers in order. For instance is "BadBrowseNameInvalid, StructureChanged, Low" = 2153775104 + 32768 + (1024) + 256 = 2153809152. The 1024 is added when info flags are used. Here we have set Limit to Low.

​
Subcategories

​
Modifier flags

​
API Examples

​
Ingestion

The following request ingest has five data points: three good, one uncertain, and one bad:

​
Retrieving raw data points

To be able to see the status codes on the data points we retrieve, we must set the includeStatus parameter to true.
With the example data from above, the response looks like this:
Notice that we don’t get the status code for the first two data points because they are exactly Good with code = 0. They are omitted as a performance optimization since most status codes are 0. For the last data point, we get both the code and the symbolic string representation.

​
List all data points

To list all data points, we can set the ignoreBadDataPoints parameter to false. Because the API treats uncertain data points as bad by default, this parameter includes both uncertain and bad data points.
Using the example data from above, the response looks like this:

​
Retrieving aggregates

The example below requests seven aggregates. The first aggregate is the number of data points included that are used in the calculations. The next three are simple counts of the number of data points with each status code present. The last three are the average, min, and max for only the good data points.
Using the example data from above, the response looks like this:
The example doesn’t include parameters to take uncertain and bad datapoints into account. Therefore, the count, average, min, and max calculations are performed ignoring uncertain and bad data points.

​
Treating uncertain data points as good

To also include the uncertain data points as if they were good, you can set the treateUncertainAsBad parameter to false. This parameter is also available for raw data points.
Using the example data from above, the response looks like this:
Treating the uncertain data point as good increases the total count to four. Notice that also the count, average, min, and max values have changed because of the additional good data point in the calculation.

​
Aggregate behavior

There are three boolean parameters that deterimine how aggregates are calculated: isStep, treatUncertainAsBad and ignoreBadDataPoints. Together, they result in 8 different combinations that gives different aggregate behavior.
  • If treatUncertainAsBad is true, uncertain data points are treated as being bad (the default).
  • If ignoreBadDataPoints is true, data points that are treated as bad will be ignored (the default). If this parameter is set to false, interpolation will stop at the beginning of each bad period.
  • if the time series is configured with isStep set to true, then there will be no interpolation between data points. The last value is always carried forward until the next data point.
The diagrams below illustrate how interpolation behaves between sample data points with different status codes. Each panel uses the same four points in time order (left to right): Good, Uncertain (grey), Bad (red), and Good. The black curve is drawn only where interpolation is valid — it simply stops at the boundary of any bad period rather than continuing toward a sample that would be excluded. The tabs below switch between the two interpolation modes. Within each tab, rows describe how uncertain points are treated and columns describe how bad periods are handled. See the legend below the matrix for the corresponding parameter values.
Last modified on May 19, 2026