Skip to main content
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.
Symbolic representationCode (decimal)Code (hexadecimal)
Good00x00000000
Uncertain10737418240x40000000
Bad21474836480x80000000

​
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

Category symbolic representationCode (decimal)Code (hexadecimal)
Good0x0…0000
Good00x00000000
GoodCallAgain110755840x00A90000
GoodCascade676986880x04090000
GoodCascadeInitializationAcknowledged671744000x04010000
GoodCascadeInitializationRequest672399360x04020000
GoodCascadeNotInvited673054720x04030000
GoodCascadeNotSelected673710080x04040000
GoodClamped31457280x00300000
GoodCommunicationEvent109445120x00A70000
GoodCompletesAsynchronously30146560x002E0000
GoodDataIgnored142213120x00D90000
GoodDependentValueChanged146800640x00E00000
GoodEdited144179200x00DC0000
GoodEdited_DependentValueChanged182190080x01160000
GoodEdited_DominantValueChanged182845440x01170000
GoodEdited_DominantValueChanged_DependentValueChanged183500800x01180000
GoodEntryInserted106168320x00A20000
GoodEntryReplaced106823680x00A30000
GoodFaultStateActive675676160x04070000
GoodInitiateFaultState676331520x04080000
GoodLocalOverride98304000x00960000
GoodMoreData108789760x00A60000
GoodNoData108134400x00A50000
GoodNonCriticalTimeout111411200x00AA0000
GoodOverload30801920x002F0000
GoodPostActionFailed144834560x00DD0000
GoodResultsMayBeIncomplete121896960x00BA0000
GoodRetransmissionQueueNotSupported146145280x00DF0000
GoodShutdownEvent110100480x00A80000
GoodSubscriptionTransferred29491200x002D0000
Uncertain0x4…0000
Uncertain10737418240x40000000
UncertainConfigurationError11082792960x420F0000
UncertainDataSubNormal10844897280x40A40000
UncertainDependentValueChanged10885529600x40E20000
UncertainDominantValueChanged10882908160x40DE0000
UncertainEngineeringUnitsExceeded10834411520x40940000
UncertainInitialValue10833100800x40920000
UncertainLastUsableValue10831790080x40900000
UncertainNoCommunicationLastUsableValue10831134720x408F0000
UncertainNotAllNodesAvailable10863247360x40C00000
UncertainReferenceNotDeleted10860625920x40BC0000
UncertainReferenceOutOfServer10808197120x406C0000
UncertainSensorCalibration11079516160x420A0000
UncertainSensorNotAccurate10833756160x40930000
UncertainSimulatedValue11078860800x42090000
UncertainSubNormal10835066880x40950000
UncertainSubstituteValue10832445440x40910000
UncertainTransducerInManual11078205440x42080000
Bad0x8…0000
Bad21474836480x80000000
BadAggregateConfigurationRejected21617704960x80DA0000
BadAggregateInvalidInputs21615083520x80D60000
BadAggregateListMismatch21613772800x80D40000
BadAggregateNotSupported21614428160x80D50000
BadAlreadyExists21656371200x81150000
BadApplicationSignatureInvalid21532508160x80580000
BadArgumentsMissing21552168960x80760000
BadAttributeIdInvalid21509570560x80350000
BadBoundNotFound21615738880x80D70000
BadBoundNotSupported21616394240x80D80000
BadBrowseDirectionInvalid21525299200x804D0000
BadBrowseNameDuplicated21538406400x80610000
BadBrowseNameInvalid21537751040x80600000
BadCertificateChainIncomplete21651128320x810D0000
BadCertificateHostNameInvalid21489254400x80160000
BadCertificateInvalid21486632960x80120000
BadCertificateIssuerRevocationUnknown21493186560x801C0000
BadCertificateIssuerRevoked21494497280x801E0000
BadCertificateIssuerTimeInvalid21488599040x80150000
BadCertificateIssuerUseNotAllowed21491220480x80190000
BadCertificatePolicyCheckFailed21655715840x81140000
BadCertificateRevocationUnknown21492531200x801B0000
BadCertificateRevoked21493841920x801D0000
BadCertificateTimeInvalid21487943680x80140000
BadCertificateUntrusted21491875840x801A0000
BadCertificateUriInvalid21489909760x80170000
BadCertificateUseNotAllowed21490565120x80180000
BadCommunicationError21478113280x80050000
BadConditionAlreadyDisabled21574451200x80980000
BadConditionAlreadyEnabled21608529920x80CC0000
BadConditionAlreadyShelved21611806720x80D10000
BadConditionBranchAlreadyAcked21610496000x80CF0000
BadConditionBranchAlreadyConfirmed21611151360x80D00000
BadConditionDisabled21575106560x80990000
BadConditionNotShelved21612462080x80D20000
BadConfigurationError21564620800x80890000
BadConnectionClosed21588869120x80AE0000
BadConnectionRejected21587558400x80AC0000
BadContentFilterInvalid21522022400x80480000
BadContinuationPointInvalid21523333120x804A0000
BadDataEncodingInvalid21511536640x80380000
BadDataEncodingUnsupported21512192000x80390000
BadDataLost21577728000x809D0000
BadDataTypeIdUnknown21485977600x80110000
BadDataUnavailable21578383360x809E0000
BadDeadbandFilterInvalid21567897600x808E0000
BadDecodingError21479424000x80070000
BadDependentValueChanged21623603200x80E30000
BadDeviceFailure21565931520x808B0000
BadDialogNotActive21609185280x80CD0000
BadDialogResponseInvalid21609840640x80CE0000
BadDisconnect21588213760x80AD0000
BadDiscoveryUrlMissing21527920640x80510000
BadDominantValueChanged21622292480x80E10000
BadDuplicateReferenceNotAllowed21541683200x80660000
BadEdited_OutOfRange21658992640x81190000
BadEdited_OutOfRange_DominantValueChanged21660958720x811C0000
BadEdited_OutOfRange_DominantValueChanged_DependentValueChanged21662269440x811E0000
BadEncodingError21478768640x80060000
BadEncodingLimitsExceeded21480079360x80080000
BadEndOfStream21590179840x80B00000
BadEntryExists21579038720x809F0000
BadEventFilterInvalid21521367040x80470000
BadEventIdUnknown21575761920x809A0000
BadEventNotAcknowledgeable21597388800x80BB0000
BadExpectedStreamToBlock21592801280x80B40000
BadFilterElementInvalid21603287040x80C40000
BadFilterLiteralInvalid21603942400x80C50000
BadFilterNotAllowed21520056320x80450000
BadFilterOperandCountMismatch21602631680x80C30000
BadFilterOperandInvalid21522677760x80490000
BadFilterOperatorInvalid21601320960x80C10000
BadFilterOperatorUnsupported21601976320x80C20000
BadHistoryOperationInvalid21548892160x80710000
BadHistoryOperationUnsupported21549547520x80720000
BadIdentityChangeNotSupported21604597760x80C60000
BadIdentityTokenInvalid21495808000x80200000
BadIdentityTokenRejected21496463360x80210000
BadIndexRangeInvalid21510225920x80360000
BadIndexRangeNoData21510881280x80370000
BadInitialValue_OutOfRange21659648000x811A0000
BadInsufficientClientProfile21556101120x807C0000
BadInternalError21476147200x80020000
BadInvalidArgument21586903040x80AB0000
BadInvalidSelfReference21542338560x80670000
BadInvalidState21589524480x80AF0000
BadInvalidTimestamp21497774080x80230000
BadInvalidTimestampArgument21598699520x80BD0000
BadLicenseExpired21651783680x810E0000
BadLicenseLimitsExceeded21652439040x810F0000
BadLicenseNotAvailable21653094400x81100000
BadMaxAgeInvalid21548236800x80700000
BadMaxConnectionsReached21594767360x80B70000
BadMessageNotAvailable21555445760x807B0000
BadMethodInvalid21551513600x80750000
BadMonitoredItemFilterInvalid21518745600x80430000
BadMonitoredItemFilterUnsupported21519400960x80440000
BadMonitoredItemIdInvalid21518090240x80420000
BadMonitoringModeInvalid21517434880x80410000
BadNoCommunication21506949120x80310000
BadNoContinuationPoints21523988480x804B0000
BadNoData21576417280x809B0000
BadNoDataAvailable21590835200x80B10000
BadNoDeleteRights21543649280x80690000
BadNoEntryExists21579694080x80A00000
BadNoMatch21547581440x806F0000
BadNoSubscription21554135040x80790000
BadNoValidCertificates21533163520x80590000
BadNodeAttributesInvalid21539061760x80620000
BadNodeClassInvalid21537095680x805F0000
BadNodeIdExists21536440320x805E0000
BadNodeIdInvalid21508259840x80330000
BadNodeIdRejected21535784960x805D0000
BadNodeIdUnknown21508915200x80340000
BadNodeNotInView21525954560x804E0000
BadNonceInvalid21498429440x80240000
BadNotConnected21565276160x808A0000
BadNotExecutable21653749760x81110000
BadNotFound21515468800x803E0000
BadNotImplemented21516779520x80400000
BadNotReadable21512847360x803A0000
BadNotSupported21514813440x803D0000
BadNotTypeDefinition21605908480x80C80000
BadNotWritable21513502720x803B0000
BadNothingToDo21484666880x800F0000
BadNumericOverflow21654405120x81120000
BadObjectDeleted21516124160x803F0000
BadOperationAbandoned21592145920x80B30000
BadOutOfMemory21476802560x80030000
BadOutOfRange21514158080x803C0000
BadOutOfRange_DominantValueChanged21660303360x811B0000
BadOutOfRange_DominantValueChanged_DependentValueChanged21661614080x811D0000
BadOutOfService21567242240x808D0000
BadParentNodeIdInvalid21534474240x805B0000
BadProtocolVersionUnsupported21599354880x80BE0000
BadQueryTooComplex21546926080x806E0000
BadReferenceLocalOnly21542993920x80680000
BadReferenceNotAllowed21535129600x805C0000
BadReferenceTypeIdInvalid21524643840x804C0000
BadRefreshInProgress21573795840x80970000
BadRequestCancelledByClient21503672320x802C0000
BadRequestCancelledByRequest21533818880x805A0000
BadRequestHeaderInvalid21502361600x802A0000
BadRequestInterrupted21561344000x80840000
BadRequestNotAllowed21624258560x80E40000
BadRequestNotComplete21655060480x81130000
BadRequestTimeout21561999360x80850000
BadRequestTooLarge21595422720x80B80000
BadRequestTypeInvalid21529231360x80530000
BadResourceUnavailable21477457920x80040000
BadResponseTooLarge21596078080x80B90000
BadSecureChannelClosed21562654720x80860000
BadSecureChannelIdInvalid21497118720x80220000
BadSecureChannelTokenUnknown21563310080x80870000
BadSecurityChecksFailed21487288320x80130000
BadSecurityModeInsufficient21625569280x80E60000
BadSecurityModeRejected21529886720x80540000
BadSecurityPolicyRejected21530542080x80550000
BadSempahoreFileMissing21528576000x80520000
BadSensorFailure21566586880x808C0000
BadSequenceNumberInvalid21563965440x80880000
BadSequenceNumberUnknown21554790400x807A0000
BadServerHalted21484011520x800E0000
BadServerIndexInvalid21544304640x806A0000
BadServerNameMissing21527265280x80500000
BadServerNotConnected21483356160x800D0000
BadServerUriInvalid21526609920x804F0000
BadServiceUnsupported21482045440x800B0000
BadSessionClosed21499740160x80260000
BadSessionIdInvalid21499084800x80250000
BadSessionNotActivated21500395520x80270000
BadShelvingTimeOutOfRange21613117440x80D30000
BadShutdown21482700800x800C0000
BadSourceNodeIdInvalid21540372480x80640000
BadStateNotActive21600010240x80BF0000
BadStructureMissing21520711680x80460000
BadSubscriptionIdInvalid21501050880x80280000
BadSyntaxError21594112000x80B60000
BadTargetNodeIdInvalid21541027840x80650000
BadTcpEndpointUrlInvalid21560688640x80830000
BadTcpInternalError21560033280x80820000
BadTcpMessageTooLarge21558722560x80800000
BadTcpMessageTypeInvalid21557411840x807E0000
BadTcpNotEnoughResources21559377920x80810000
BadTcpSecureChannelUnknown21558067200x807F0000
BadTcpServerTooBusy21556756480x807D0000
BadTicketInvalid21663580160x81200000
BadTicketRequired21662924800x811F0000
BadTimeout21481390080x800A0000
BadTimestampNotSupported21580349440x80A10000
BadTimestampsToReturnInvalid21503016960x802B0000
BadTooManyArguments21624913920x80E50000
BadTooManyMatches21546270720x806D0000
BadTooManyMonitoredItems21618360320x80DB0000
BadTooManyOperations21485322240x80100000
BadTooManyPublishRequests21553479680x80780000
BadTooManySessions21531197440x80560000
BadTooManySubscriptions21552824320x80770000
BadTypeDefinitionInvalid21539717120x80630000
BadTypeMismatch21550858240x80740000
BadUnexpectedError21475491840x80010000
BadUnknownResponse21480734720x80090000
BadUserAccessDenied21495152640x801F0000
BadUserSignatureInvalid21531852800x80570000
BadViewIdUnknown21544960000x806B0000
BadViewParameterMismatch21607219200x80CA0000
BadViewTimestampInvalid21606563840x80C90000
BadViewVersionInvalid21607874560x80CB0000
BadWaitingForInitialData21507604480x80320000
BadWaitingForResponse21591490560x80B20000
BadWouldBlock21593456640x80B50000
BadWriteNotSupported21550202880x80730000

​
Modifier flags

Modifier symbolic representationCode (decimal)Code (hexadecimal)
, StructureChanged327680x8000
, SemanticsChanged163840x4000
Add the following number if and only if any of the below info flags are added
10240x0400
Only one of the following 3 limit flags may be set.
, Constant7680x0300
, High5120x0200
, Low2560x0100
Other info flags:
, Overflow1280x0080
, MultipleValues160x0010
, ExtraData80x0008
, Partial40x0004
Only one of interpolated and calculated can be set.
, Interpolated20x0002
, Calculated10x0001

​
API Examples

​
Ingestion

The following request ingest has five data points: three good, one uncertain, and one bad: 
POST /api/v1/projects/{project}/timeseries/data
Content-Type: application/json

{
    "items": [
        {
            "externalId": "outside-temperature",
            "datapoints": [
                {
                    "timestamp": 1620000000000,
                    "value": 1
                },
                {
                    "timestamp": 1620000000001,
                    "value": 2,
                    "status": {
                        "code": 0
                    }
                },
                {
                    "timestamp": 1620000000002,
                    "value": 3,
                    "status": {
                        "symbol": "GoodClamped"
                    }
                },
                {
                    "timestamp": 1620000000003,
                    "value": 4,
                    "status": {
                        "symbol": "Uncertain"
                    }
                },
                {
                    "timestamp": 1620000000004,
                    "value": 5,
                    "status": {
                        "code": 2153809152
                    }
                }
            ]
        }
    ]
}

​
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. 
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json

{
    "items": [
        {
            "externalId": "outside-temperature",
            "includeStatus": true,
        }
    ]
}
With the example data from above, the response looks like this: 
{
    "items": [
        {
            // ...
            "datapoints": [
                {
                    "timestamp": 1620000000000,
                    "value": 1.0
                },
                {
                    "timestamp": 1620000000001,
                    "value": 2.0
                },
                {
                    "timestamp": 1620000000002,
                    "value": 3.0,
                    "status": {
                        "code": 3145728,
                        "symbol": "GoodClamped"
                    }
                }
            ]
        }
    ]
}
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. 
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json

{
    "items": [
        {
            "externalId": "outside-temperature",
            "includeStatus": true,
            "ignoreBadDataPoints": false,
        }
    ]
}
Using the example data from above, the response looks like this: 
{
    "items": [
        {
            // ...
            "datapoints": [
                {
                    "timestamp": 1620000000000,
                    "value": 1.0
                },
                {
                    "timestamp": 1620000000001,
                    "value": 2.0
                },
                {
                    "timestamp": 1620000000002,
                    "value": 3.0,
                    "status": {
                        "code": 3145728,
                        "symbol": "GoodClamped"
                    }
                },
                {
                    "timestamp": 1620000000003,
                    "value": 4.0,
                    "status": {
                        "code": 1073741824,
                        "symbol": "Uncertain"
                    }
                },
                {
                    "timestamp": 1620000000004,
                    "value": 5.0,
                    "status": {
                        "code": 2153809152,
                        "symbol": "BadBrowseNameInvalid, StructureChanged, Low"
                    }
                }
            ]
        }
    ]
}

​
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. 
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json

{
    "items": [
        {
            "externalId": "outside-temperature",
            "granularity": "1s",
            "aggregates": [
                "count",
                "countGood", "countUncertain", "countBad",
                "average", "min", "max"
            ]
        }
    ]
}
Using the example data from above, the response looks like this: 
{
    "items": [
        {
            // ...
            "datapoints": [
                {
                    "timestamp": 1620000000000,
                    "count": 3,
                    "countGood": 3,
                    "countUncertain": 1,
                    "countBad": 1,
                    "average": 2.0,
                    "min": 1.0,
                    "max": 3.0
                }
            ]
        }
    ]
}
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. 
POST /api/v1/projects/{project}/timeseries/data/list
Content-Type: application/json

{
    "items": [
        {
            "externalId": "outside-temperature",
            "granularity": "1s",
            "treatUncertainAsBad": false,
            "aggregates": [
                "count",
                "countGood", "countUncertain", "countBad",
                "average", "min", "max"
            ]
        }
    ]
}
Using the example data from above, the response looks like this: 
{
    "items": [
        {
            // ...
            "datapoints": [
                {
                    "timestamp": 1620000000000,
                    "count": 4,
                    "countGood": 3,
                    "countUncertain": 1,
                    "countBad": 1,
                    "average": 2.5,
                    "min": 1.0,
                    "max": 4.0
                }
            ]
        }
    ]
}
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 image below illustrates how we interpolate between data points with different status codes in each of the 8 combinations.
Interpolation between data points with different status codes