> ## Documentation Index > Fetch the complete documentation index at: https://docs.cognite.com/llms.txt > Use this file to discover all available pages before exploring further. # Status codes > Learn how status codes determine the quality of time series data points and impact data retrieval, aggregate computation, and visualization. export const StatusContKeepBadTreatUncAsGood = () => {"Continuous; export const StatusContIgnoreBadTreatUncAsGood = () => {"Continuous; export const StatusContKeepBadTreatUncAsBad = () => {"Continuous; export const StatusContIgnoreBadTreatUncAsBad = () => {"Continuous; export const StatusStepKeepBadTreatUncAsGood = () => {"Stepwise; export const StatusStepIgnoreBadTreatUncAsGood = () => {"Stepwise; export const StatusStepKeepBadTreatUncAsBad = () => {"Stepwise; export const StatusStepIgnoreBadTreatUncAsBad = () => {"Stepwise; Examples use `externalId` for asset-centric projects. For data modeling, use `instanceId` instead. See [Time series and datapoints](/api-reference/concepts/20230101/time-series-data) 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][opcua-extractor] and [PI extractors][pi-extractor] 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. [opcua-extractor]: /cdf/integration/guides/extraction/opc_ua/ [pi-extractor]: /cdf/integration/guides/extraction/pi ## 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 representation | Code (decimal) | Code (hexadecimal) | | ----------------------- | -------------- | ------------------ | | Good | 0 | 0x00000000 | | Uncertain | 1073741824 | 0x40000000 | | Bad | 2147483648 | 0x80000000 | ### 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 representation | Code (decimal) | Code (hexadecimal) | | ------------------------------------------------------------------ | -------------- | ------------------ | | **Good** | | **0x0...0000** | | Good | 0 | 0x00000000 | | GoodCallAgain | 11075584 | 0x00A90000 | | GoodCascade | 67698688 | 0x04090000 | | GoodCascadeInitializationAcknowledged | 67174400 | 0x04010000 | | GoodCascadeInitializationRequest | 67239936 | 0x04020000 | | GoodCascadeNotInvited | 67305472 | 0x04030000 | | GoodCascadeNotSelected | 67371008 | 0x04040000 | | GoodClamped | 3145728 | 0x00300000 | | GoodCommunicationEvent | 10944512 | 0x00A70000 | | GoodCompletesAsynchronously | 3014656 | 0x002E0000 | | GoodDataIgnored | 14221312 | 0x00D90000 | | GoodDependentValueChanged | 14680064 | 0x00E00000 | | GoodEdited | 14417920 | 0x00DC0000 | | GoodEdited\_DependentValueChanged | 18219008 | 0x01160000 | | GoodEdited\_DominantValueChanged | 18284544 | 0x01170000 | | GoodEdited\_DominantValueChanged\_DependentValueChanged | 18350080 | 0x01180000 | | GoodEntryInserted | 10616832 | 0x00A20000 | | GoodEntryReplaced | 10682368 | 0x00A30000 | | GoodFaultStateActive | 67567616 | 0x04070000 | | GoodInitiateFaultState | 67633152 | 0x04080000 | | GoodLocalOverride | 9830400 | 0x00960000 | | GoodMoreData | 10878976 | 0x00A60000 | | GoodNoData | 10813440 | 0x00A50000 | | GoodNonCriticalTimeout | 11141120 | 0x00AA0000 | | GoodOverload | 3080192 | 0x002F0000 | | GoodPostActionFailed | 14483456 | 0x00DD0000 | | GoodResultsMayBeIncomplete | 12189696 | 0x00BA0000 | | GoodRetransmissionQueueNotSupported | 14614528 | 0x00DF0000 | | GoodShutdownEvent | 11010048 | 0x00A80000 | | GoodSubscriptionTransferred | 2949120 | 0x002D0000 | | **Uncertain** | | **0x4...0000** | | Uncertain | 1073741824 | 0x40000000 | | UncertainConfigurationError | 1108279296 | 0x420F0000 | | UncertainDataSubNormal | 1084489728 | 0x40A40000 | | UncertainDependentValueChanged | 1088552960 | 0x40E20000 | | UncertainDominantValueChanged | 1088290816 | 0x40DE0000 | | UncertainEngineeringUnitsExceeded | 1083441152 | 0x40940000 | | UncertainInitialValue | 1083310080 | 0x40920000 | | UncertainLastUsableValue | 1083179008 | 0x40900000 | | UncertainNoCommunicationLastUsableValue | 1083113472 | 0x408F0000 | | UncertainNotAllNodesAvailable | 1086324736 | 0x40C00000 | | UncertainReferenceNotDeleted | 1086062592 | 0x40BC0000 | | UncertainReferenceOutOfServer | 1080819712 | 0x406C0000 | | UncertainSensorCalibration | 1107951616 | 0x420A0000 | | UncertainSensorNotAccurate | 1083375616 | 0x40930000 | | UncertainSimulatedValue | 1107886080 | 0x42090000 | | UncertainSubNormal | 1083506688 | 0x40950000 | | UncertainSubstituteValue | 1083244544 | 0x40910000 | | UncertainTransducerInManual | 1107820544 | 0x42080000 | | **Bad** | | **0x8...0000** | | Bad | 2147483648 | 0x80000000 | | BadAggregateConfigurationRejected | 2161770496 | 0x80DA0000 | | BadAggregateInvalidInputs | 2161508352 | 0x80D60000 | | BadAggregateListMismatch | 2161377280 | 0x80D40000 | | BadAggregateNotSupported | 2161442816 | 0x80D50000 | | BadAlreadyExists | 2165637120 | 0x81150000 | | BadApplicationSignatureInvalid | 2153250816 | 0x80580000 | | BadArgumentsMissing | 2155216896 | 0x80760000 | | BadAttributeIdInvalid | 2150957056 | 0x80350000 | | BadBoundNotFound | 2161573888 | 0x80D70000 | | BadBoundNotSupported | 2161639424 | 0x80D80000 | | BadBrowseDirectionInvalid | 2152529920 | 0x804D0000 | | BadBrowseNameDuplicated | 2153840640 | 0x80610000 | | BadBrowseNameInvalid | 2153775104 | 0x80600000 | | BadCertificateChainIncomplete | 2165112832 | 0x810D0000 | | BadCertificateHostNameInvalid | 2148925440 | 0x80160000 | | BadCertificateInvalid | 2148663296 | 0x80120000 | | BadCertificateIssuerRevocationUnknown | 2149318656 | 0x801C0000 | | BadCertificateIssuerRevoked | 2149449728 | 0x801E0000 | | BadCertificateIssuerTimeInvalid | 2148859904 | 0x80150000 | | BadCertificateIssuerUseNotAllowed | 2149122048 | 0x80190000 | | BadCertificatePolicyCheckFailed | 2165571584 | 0x81140000 | | BadCertificateRevocationUnknown | 2149253120 | 0x801B0000 | | BadCertificateRevoked | 2149384192 | 0x801D0000 | | BadCertificateTimeInvalid | 2148794368 | 0x80140000 | | BadCertificateUntrusted | 2149187584 | 0x801A0000 | | BadCertificateUriInvalid | 2148990976 | 0x80170000 | | BadCertificateUseNotAllowed | 2149056512 | 0x80180000 | | BadCommunicationError | 2147811328 | 0x80050000 | | BadConditionAlreadyDisabled | 2157445120 | 0x80980000 | | BadConditionAlreadyEnabled | 2160852992 | 0x80CC0000 | | BadConditionAlreadyShelved | 2161180672 | 0x80D10000 | | BadConditionBranchAlreadyAcked | 2161049600 | 0x80CF0000 | | BadConditionBranchAlreadyConfirmed | 2161115136 | 0x80D00000 | | BadConditionDisabled | 2157510656 | 0x80990000 | | BadConditionNotShelved | 2161246208 | 0x80D20000 | | BadConfigurationError | 2156462080 | 0x80890000 | | BadConnectionClosed | 2158886912 | 0x80AE0000 | | BadConnectionRejected | 2158755840 | 0x80AC0000 | | BadContentFilterInvalid | 2152202240 | 0x80480000 | | BadContinuationPointInvalid | 2152333312 | 0x804A0000 | | BadDataEncodingInvalid | 2151153664 | 0x80380000 | | BadDataEncodingUnsupported | 2151219200 | 0x80390000 | | BadDataLost | 2157772800 | 0x809D0000 | | BadDataTypeIdUnknown | 2148597760 | 0x80110000 | | BadDataUnavailable | 2157838336 | 0x809E0000 | | BadDeadbandFilterInvalid | 2156789760 | 0x808E0000 | | BadDecodingError | 2147942400 | 0x80070000 | | BadDependentValueChanged | 2162360320 | 0x80E30000 | | BadDeviceFailure | 2156593152 | 0x808B0000 | | BadDialogNotActive | 2160918528 | 0x80CD0000 | | BadDialogResponseInvalid | 2160984064 | 0x80CE0000 | | BadDisconnect | 2158821376 | 0x80AD0000 | | BadDiscoveryUrlMissing | 2152792064 | 0x80510000 | | BadDominantValueChanged | 2162229248 | 0x80E10000 | | BadDuplicateReferenceNotAllowed | 2154168320 | 0x80660000 | | BadEdited\_OutOfRange | 2165899264 | 0x81190000 | | BadEdited\_OutOfRange\_DominantValueChanged | 2166095872 | 0x811C0000 | | BadEdited\_OutOfRange\_DominantValueChanged\_DependentValueChanged | 2166226944 | 0x811E0000 | | BadEncodingError | 2147876864 | 0x80060000 | | BadEncodingLimitsExceeded | 2148007936 | 0x80080000 | | BadEndOfStream | 2159017984 | 0x80B00000 | | BadEntryExists | 2157903872 | 0x809F0000 | | BadEventFilterInvalid | 2152136704 | 0x80470000 | | BadEventIdUnknown | 2157576192 | 0x809A0000 | | BadEventNotAcknowledgeable | 2159738880 | 0x80BB0000 | | BadExpectedStreamToBlock | 2159280128 | 0x80B40000 | | BadFilterElementInvalid | 2160328704 | 0x80C40000 | | BadFilterLiteralInvalid | 2160394240 | 0x80C50000 | | BadFilterNotAllowed | 2152005632 | 0x80450000 | | BadFilterOperandCountMismatch | 2160263168 | 0x80C30000 | | BadFilterOperandInvalid | 2152267776 | 0x80490000 | | BadFilterOperatorInvalid | 2160132096 | 0x80C10000 | | BadFilterOperatorUnsupported | 2160197632 | 0x80C20000 | | BadHistoryOperationInvalid | 2154889216 | 0x80710000 | | BadHistoryOperationUnsupported | 2154954752 | 0x80720000 | | BadIdentityChangeNotSupported | 2160459776 | 0x80C60000 | | BadIdentityTokenInvalid | 2149580800 | 0x80200000 | | BadIdentityTokenRejected | 2149646336 | 0x80210000 | | BadIndexRangeInvalid | 2151022592 | 0x80360000 | | BadIndexRangeNoData | 2151088128 | 0x80370000 | | BadInitialValue\_OutOfRange | 2165964800 | 0x811A0000 | | BadInsufficientClientProfile | 2155610112 | 0x807C0000 | | BadInternalError | 2147614720 | 0x80020000 | | BadInvalidArgument | 2158690304 | 0x80AB0000 | | BadInvalidSelfReference | 2154233856 | 0x80670000 | | BadInvalidState | 2158952448 | 0x80AF0000 | | BadInvalidTimestamp | 2149777408 | 0x80230000 | | BadInvalidTimestampArgument | 2159869952 | 0x80BD0000 | | BadLicenseExpired | 2165178368 | 0x810E0000 | | BadLicenseLimitsExceeded | 2165243904 | 0x810F0000 | | BadLicenseNotAvailable | 2165309440 | 0x81100000 | | BadMaxAgeInvalid | 2154823680 | 0x80700000 | | BadMaxConnectionsReached | 2159476736 | 0x80B70000 | | BadMessageNotAvailable | 2155544576 | 0x807B0000 | | BadMethodInvalid | 2155151360 | 0x80750000 | | BadMonitoredItemFilterInvalid | 2151874560 | 0x80430000 | | BadMonitoredItemFilterUnsupported | 2151940096 | 0x80440000 | | BadMonitoredItemIdInvalid | 2151809024 | 0x80420000 | | BadMonitoringModeInvalid | 2151743488 | 0x80410000 | | BadNoCommunication | 2150694912 | 0x80310000 | | BadNoContinuationPoints | 2152398848 | 0x804B0000 | | BadNoData | 2157641728 | 0x809B0000 | | BadNoDataAvailable | 2159083520 | 0x80B10000 | | BadNoDeleteRights | 2154364928 | 0x80690000 | | BadNoEntryExists | 2157969408 | 0x80A00000 | | BadNoMatch | 2154758144 | 0x806F0000 | | BadNoSubscription | 2155413504 | 0x80790000 | | BadNoValidCertificates | 2153316352 | 0x80590000 | | BadNodeAttributesInvalid | 2153906176 | 0x80620000 | | BadNodeClassInvalid | 2153709568 | 0x805F0000 | | BadNodeIdExists | 2153644032 | 0x805E0000 | | BadNodeIdInvalid | 2150825984 | 0x80330000 | | BadNodeIdRejected | 2153578496 | 0x805D0000 | | BadNodeIdUnknown | 2150891520 | 0x80340000 | | BadNodeNotInView | 2152595456 | 0x804E0000 | | BadNonceInvalid | 2149842944 | 0x80240000 | | BadNotConnected | 2156527616 | 0x808A0000 | | BadNotExecutable | 2165374976 | 0x81110000 | | BadNotFound | 2151546880 | 0x803E0000 | | BadNotImplemented | 2151677952 | 0x80400000 | | BadNotReadable | 2151284736 | 0x803A0000 | | BadNotSupported | 2151481344 | 0x803D0000 | | BadNotTypeDefinition | 2160590848 | 0x80C80000 | | BadNotWritable | 2151350272 | 0x803B0000 | | BadNothingToDo | 2148466688 | 0x800F0000 | | BadNumericOverflow | 2165440512 | 0x81120000 | | BadObjectDeleted | 2151612416 | 0x803F0000 | | BadOperationAbandoned | 2159214592 | 0x80B30000 | | BadOutOfMemory | 2147680256 | 0x80030000 | | BadOutOfRange | 2151415808 | 0x803C0000 | | BadOutOfRange\_DominantValueChanged | 2166030336 | 0x811B0000 | | BadOutOfRange\_DominantValueChanged\_DependentValueChanged | 2166161408 | 0x811D0000 | | BadOutOfService | 2156724224 | 0x808D0000 | | BadParentNodeIdInvalid | 2153447424 | 0x805B0000 | | BadProtocolVersionUnsupported | 2159935488 | 0x80BE0000 | | BadQueryTooComplex | 2154692608 | 0x806E0000 | | BadReferenceLocalOnly | 2154299392 | 0x80680000 | | BadReferenceNotAllowed | 2153512960 | 0x805C0000 | | BadReferenceTypeIdInvalid | 2152464384 | 0x804C0000 | | BadRefreshInProgress | 2157379584 | 0x80970000 | | BadRequestCancelledByClient | 2150367232 | 0x802C0000 | | BadRequestCancelledByRequest | 2153381888 | 0x805A0000 | | BadRequestHeaderInvalid | 2150236160 | 0x802A0000 | | BadRequestInterrupted | 2156134400 | 0x80840000 | | BadRequestNotAllowed | 2162425856 | 0x80E40000 | | BadRequestNotComplete | 2165506048 | 0x81130000 | | BadRequestTimeout | 2156199936 | 0x80850000 | | BadRequestTooLarge | 2159542272 | 0x80B80000 | | BadRequestTypeInvalid | 2152923136 | 0x80530000 | | BadResourceUnavailable | 2147745792 | 0x80040000 | | BadResponseTooLarge | 2159607808 | 0x80B90000 | | BadSecureChannelClosed | 2156265472 | 0x80860000 | | BadSecureChannelIdInvalid | 2149711872 | 0x80220000 | | BadSecureChannelTokenUnknown | 2156331008 | 0x80870000 | | BadSecurityChecksFailed | 2148728832 | 0x80130000 | | BadSecurityModeInsufficient | 2162556928 | 0x80E60000 | | BadSecurityModeRejected | 2152988672 | 0x80540000 | | BadSecurityPolicyRejected | 2153054208 | 0x80550000 | | BadSempahoreFileMissing | 2152857600 | 0x80520000 | | BadSensorFailure | 2156658688 | 0x808C0000 | | BadSequenceNumberInvalid | 2156396544 | 0x80880000 | | BadSequenceNumberUnknown | 2155479040 | 0x807A0000 | | BadServerHalted | 2148401152 | 0x800E0000 | | BadServerIndexInvalid | 2154430464 | 0x806A0000 | | BadServerNameMissing | 2152726528 | 0x80500000 | | BadServerNotConnected | 2148335616 | 0x800D0000 | | BadServerUriInvalid | 2152660992 | 0x804F0000 | | BadServiceUnsupported | 2148204544 | 0x800B0000 | | BadSessionClosed | 2149974016 | 0x80260000 | | BadSessionIdInvalid | 2149908480 | 0x80250000 | | BadSessionNotActivated | 2150039552 | 0x80270000 | | BadShelvingTimeOutOfRange | 2161311744 | 0x80D30000 | | BadShutdown | 2148270080 | 0x800C0000 | | BadSourceNodeIdInvalid | 2154037248 | 0x80640000 | | BadStateNotActive | 2160001024 | 0x80BF0000 | | BadStructureMissing | 2152071168 | 0x80460000 | | BadSubscriptionIdInvalid | 2150105088 | 0x80280000 | | BadSyntaxError | 2159411200 | 0x80B60000 | | BadTargetNodeIdInvalid | 2154102784 | 0x80650000 | | BadTcpEndpointUrlInvalid | 2156068864 | 0x80830000 | | BadTcpInternalError | 2156003328 | 0x80820000 | | BadTcpMessageTooLarge | 2155872256 | 0x80800000 | | BadTcpMessageTypeInvalid | 2155741184 | 0x807E0000 | | BadTcpNotEnoughResources | 2155937792 | 0x80810000 | | BadTcpSecureChannelUnknown | 2155806720 | 0x807F0000 | | BadTcpServerTooBusy | 2155675648 | 0x807D0000 | | BadTicketInvalid | 2166358016 | 0x81200000 | | BadTicketRequired | 2166292480 | 0x811F0000 | | BadTimeout | 2148139008 | 0x800A0000 | | BadTimestampNotSupported | 2158034944 | 0x80A10000 | | BadTimestampsToReturnInvalid | 2150301696 | 0x802B0000 | | BadTooManyArguments | 2162491392 | 0x80E50000 | | BadTooManyMatches | 2154627072 | 0x806D0000 | | BadTooManyMonitoredItems | 2161836032 | 0x80DB0000 | | BadTooManyOperations | 2148532224 | 0x80100000 | | BadTooManyPublishRequests | 2155347968 | 0x80780000 | | BadTooManySessions | 2153119744 | 0x80560000 | | BadTooManySubscriptions | 2155282432 | 0x80770000 | | BadTypeDefinitionInvalid | 2153971712 | 0x80630000 | | BadTypeMismatch | 2155085824 | 0x80740000 | | BadUnexpectedError | 2147549184 | 0x80010000 | | BadUnknownResponse | 2148073472 | 0x80090000 | | BadUserAccessDenied | 2149515264 | 0x801F0000 | | BadUserSignatureInvalid | 2153185280 | 0x80570000 | | BadViewIdUnknown | 2154496000 | 0x806B0000 | | BadViewParameterMismatch | 2160721920 | 0x80CA0000 | | BadViewTimestampInvalid | 2160656384 | 0x80C90000 | | BadViewVersionInvalid | 2160787456 | 0x80CB0000 | | BadWaitingForInitialData | 2150760448 | 0x80320000 | | BadWaitingForResponse | 2159149056 | 0x80B20000 | | BadWouldBlock | 2159345664 | 0x80B50000 | | BadWriteNotSupported | 2155020288 | 0x80730000 | ## Modifier flags | Modifier symbolic representation | Code (decimal) | Code (hexadecimal) | | ------------------------------------------------------------------------------- | -------------- | ------------------ | | , StructureChanged | 32768 | 0x8000 | | , SemanticsChanged | 16384 | 0x4000 | | Add the following number if and only if any of the below *info flags* are added | | | | | 1024 | 0x0400 | | Only one of the following 3 limit flags may be set. | | | | , Constant | 768 | 0x0300 | | , High | 512 | 0x0200 | | , Low | 256 | 0x0100 | | Other info flags: | | | | , Overflow | 128 | 0x0080 | | , MultipleValues | 16 | 0x0010 | | , ExtraData | 8 | 0x0008 | | , Partial | 4 | 0x0004 | | Only one of interpolated and calculated can be set. | | | | , Interpolated | 2 | 0x0002 | | , Calculated | 1 | 0x0001 | ## API Examples ### Ingestion The following request ingest has five data points: three good, one uncertain, and one bad: ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} 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. ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} 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: ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} { "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. ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} 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: ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} { "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. ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} 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: ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} { "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. ```json theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} 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: ```json wrap theme={"languages":{"custom":["/_languages/kuiper.json","../_languages/kuiper.json"]}} { "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 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. | | Skip bad periods *(default)* | Stop at bad periods | | -------------------------------- | ---------------------------------------------------- | -------------------------------------------------- | | **Uncertain as bad** *(default)* | | | | **Uncertain as good** | | | | | Skip bad periods *(default)* | Stop at bad periods | | -------------------------------- | ---------------------------------------------------- | -------------------------------------------------- | | **Uncertain as bad** *(default)* | | | | **Uncertain as good** | | | | Label | Parameter | | ------------------- | -------------------------------------- | | Stepwise | `isStep=true` | | Continuous | `isStep=false` *(default)* | | Uncertain as bad | `treatUncertainAsBad=true` *(default)* | | Uncertain as good | `treatUncertainAsBad=false` | | Skip bad periods | `ignoreBadDataPoints=true` *(default)* | | Stop at bad periods | `ignoreBadDataPoints=false` |