Skip to main content

GraphQL reference: event-management

Generated from the schema this service serves, so it cannot fall behind it. The same schema is published as a file for tools and agents.

Endpointhttps://<your-host>/api/event-management/graphql
Auth planetenant — The ordinary application plane. Obtain a tenant access token by calling login then selectTenant on user-management, and authorize each call with the capability it names (for example device:write).
Authorize withtenant access token
Schema file/schema/event-management.graphql
Described258 of 258 elements

Queries​

alertEvents · bucketedMeasurements · calculatedEvents · calculatedMetricBackfill · calculatedMetricBackfillAvailability · calculatedMetricBackfills · events · failedEventCount · failedEventSummary · failedEvents · locationEvents · measurementEvents · stateChangeEvents

alertEvents​

Searches stored device alerts, newest first by occurred time, one page at a time. Requires event:read. A member whose access is limited to some customers sees only events recorded while the device belonged to one of them.

Returns AlertEventSearchResults!

ArgumentTypeDescription
criteriaEventSearchCriteria!Filters and page to return.

bucketedMeasurements​

Aggregates measurements into fixed-width time buckets (average, minimum, maximum, sum and count) per measurement name, ordered by bucket start and then name. startTime is required, and a request covering more than 10,000 buckets (range / intervalSeconds, rounded up) is refused with LIMIT_EXCEEDED; because buckets align to fixed instants, a result can hold one more bucket per name than that count. A result of more than 50,000 rows (buckets times measurement names) is also refused with LIMIT_EXCEEDED. Returns an empty list when nothing matches. Requires event:read. A member whose access is limited to some customers sees only events recorded while the device belonged to one of them.

Returns [MeasurementBucket!]!

ArgumentTypeDescription
criteriaMeasurementAggregationCriteria!Filters and bucket width.

calculatedEvents​

Evaluates a DRAFT calculated-metric formula over one device's stored readings, for previewing the formula while it is being written: each sample (the readings of one stored event that share one instant) is evaluated as it would be when readings are recorded, and returned with its inputs and its value or the reason it produced none. The formula is checked as a publish checks it, and an invalid one is refused. Inputs are the values as stored, to inputDecimalPlaces decimal places, so a result can differ from the value computed from the full-precision reading. Only the inputs the formula reads are fetched and returned, so an event holding none of them is not a sample. The range must be longer than zero and at most 7 days; a range holding more than 50,000 samples, or more than 250,000 input values, is refused with LIMIT_EXCEEDED rather than truncated. Nothing is stored. Requires event:read. A member whose access is limited to some customers sees only events recorded while the device belonged to one of them.

Returns CalculatedEventsResult!

ArgumentTypeDescription
constants[CalculatedConstant!]The values of the device constants the formula reads as device.name, as the device's metadata holds them now, at most 32. Every sample is evaluated with these same values: they are the device's current constants, not the ones its history was recorded under. A constant the formula reads and this omits is absent, so its samples are skipped as missing_input. Omit this when the formula reads none.
dataTypeString!The calculated metric's data type: DOUBLE, INT or BOOLEAN.
deviceTokenString!Token of the device whose readings to evaluate.
expressionString!The formula, as written on the calculated metric.
fromString!Start of the range by occurred time, as an RFC 3339 timestamp.
inputs[CalculatedInput!]!The metrics the formula reads, with their data types: measured ones, and calculated ones, whose stored values are read like a measured one's: rounded as stored, and as computed by the formula that was published when each reading arrived.
maxValueFloatLargest value the metric may take; a result above it is skipped as range.
minValueFloatSmallest value the metric may take; a result below it is skipped as range.
toString!End of the range by occurred time, as an RFC 3339 timestamp; after from, by at most 7 days.

calculatedMetricBackfill​

One calculated-metric backfill job of the tenant. Null when the tenant has none with that token. Requires event:read; customer-scoped callers are refused with FORBIDDEN.

Returns CalculatedMetricBackfill

ArgumentTypeDescription
tokenString!The job's token.

calculatedMetricBackfillAvailability​

Whether this instance can run a calculated-metric backfill at all, so a client can disable its backfill control up front instead of learning from a refused start. available is false when the backfill worker is switched off, its pool is too small to run, or device-management is not configured; reason then says why, in the same words a refused start carries in UNAVAILABLE. It answers for the instance, not the tenant: a true answer does not promise a start will be accepted (a range, a metric or an already-active job can still refuse it). Requires event:read; customer-scoped callers are refused with FORBIDDEN.

Returns CalculatedMetricBackfillAvailability!

calculatedMetricBackfills​

The tenant's calculated-metric backfill jobs, newest first, a page at a time. Requires event:read; customer-scoped callers are refused with FORBIDDEN. A first outside 1..100 or an after that was not given by this list is refused with INVALID_VALUE.

Returns CalculatedMetricBackfillConnection!

ArgumentTypeDescription
afterStringThe nextCursor of the previous page; omit for the first page.
firstIntPage size, 1 to 100; defaults to 25.
profileTokenStringOnly the jobs of this profile.
statuses[CalculatedMetricBackfillStatus!]Only jobs in one of these statuses.

events​

Searches stored event envelopes, newest first by occurred time, one page at a time. Requires event:read. A member whose access is limited to some customers sees only events recorded while the device belonged to one of them.

Returns EventSearchResults!

ArgumentTypeDescription
criteriaEventSearchCriteria!Filters and page to return.

failedEventCount​

How many events were refused for one claimed device token since an instant, including records folded into a count. Drives "N events from this device were rejected". Requires device:write; customer-scoped callers are refused with FORBIDDEN. A since older than 31 days is treated as 31 days ago, and a deviceToken of "*" is refused with INVALID_VALUE.

Returns Int!

ArgumentTypeDescription
deviceTokenString!The device token, as the sender names it.
sinceString!Count failures recorded at or after this instant, an RFC 3339 timestamp.

failedEventSummary​

Counts the tenant's failures per reason since an instant, with the devices with the most of each. Records folded into a count are included. Requires device:write; customer-scoped callers are refused with FORBIDDEN. since is an RFC 3339 timestamp; a value older than 31 days is treated as 31 days ago. Reasons with no records are omitted.

Returns [FailedEventReasonCount!]!

ArgumentTypeDescription
sinceString!Count failures recorded at or after this instant.

failedEvents​

The events the platform refused or could not store for this tenant, newest first, a page at a time: the answer to "why is my device's data not showing up". Each record names the reason, the device token the sender claimed and the platform's error. Records are kept for 7 days by default (an operator can change it) and are not a queue: nothing is re-sent. Requires device:write; customer-scoped callers are refused with FORBIDDEN. A since or until that is not RFC 3339, or a deviceToken of "*", is refused with INVALID_VALUE. With no since, the list covers the last 31 days, and an older since is treated as 31 days ago.

Returns FailedEventSearchResults!

ArgumentTypeDescription
criteriaFailedEventSearchCriteria!Filters and page to return.

locationEvents​

Searches stored location fixes, newest first by occurred time, one page at a time. Requires location:read, which is separate from event:read. A member whose access is limited to some customers sees only events recorded while the device belonged to one of them.

Returns LocationEventSearchResults!

ArgumentTypeDescription
criteriaEventSearchCriteria!Filters and page to return.

measurementEvents​

Searches stored measurements, newest first by occurred time, one page at a time. Requires event:read. A member whose access is limited to some customers sees only events recorded while the device belonged to one of them.

Returns MeasurementEventSearchResults!

ArgumentTypeDescription
criteriaEventSearchCriteria!Filters and page to return.

stateChangeEvents​

Searches the presence transitions of devices (connected, disconnected, demoted), newest first by occurred time, one page at a time. Filter by deviceToken and bound the range with startTime and endTime. Requires event:read. A member whose access is limited to some customers sees only transitions recorded while the device belonged to one of them.

Returns StateChangeEventSearchResults!

ArgumentTypeDescription
criteriaEventSearchCriteria!Filters and page to return.

Mutations​

cancelCalculatedMetricBackfill · startCalculatedMetricBackfill

cancelCalculatedMetricBackfill​

Cancels a backfill. A queued job is cancelled at once; a running job stops at its next commit, so its status reads RUNNING with cancelRequestedAt set until then. Rows already written stay. Requires device:write; customer-scoped callers are refused with FORBIDDEN. NOT_FOUND for a token the tenant has no job for; CONFLICT when the job already finished.

Returns CalculatedMetricBackfill!

ArgumentTypeDescription
tokenString!The token of the job to cancel.

startCalculatedMetricBackfill​

Starts a backfill: computes the calculated metrics of a published profile version for stored readings that have no value for them, and writes the missing values. It never changes a value that is already stored. The job runs in the background; read it with calculatedMetricBackfill. Requires device:write; customer-scoped callers are refused with FORBIDDEN. Refusals: INVALID_VALUE for a from or to that is not an RFC 3339 timestamp, an empty profileToken or a version below 1, for a range that is empty, in the future, longer than 90 days or older than retention allows (it is refused, never shortened), for a metric the version does not calculate or whose formula cannot run, for omitted metricKeys when no metric is new in the version, for more than 1000 devices or an empty device token, and for a device that is not of the profile; NOT_FOUND for an unknown profile or an unpublished version; CONFLICT, naming the active job, when the tenant already has one; UNAVAILABLE when the backfill worker is switched off or cannot run on this instance, or device-management cannot be reached.

Returns CalculatedMetricBackfill!

ArgumentTypeDescription
inputCalculatedMetricBackfillInput!The profile, version, metrics, range and devices to fill.

Subscriptions​

measurementStream

measurementStream​

Streams measurements as they arrive, live from the moment of subscription: there is no historical backfill, so use measurementEvents for history. Scoped to the caller's tenant and optionally filtered to one device and/or one measurement name. Requires event:read. A member whose access is limited to some customers receives only measurements recorded while the device belongs to one of them; a stream for any other device stays silent.

Returns MeasurementEvent!

ArgumentTypeDescription
deviceTokenStringOnly measurements from this device. Omit for all devices.
nameStringOnly measurements with this name. Omit for all names.

Objects​

AlertEvent · AlertEventSearchResults · CalculatedEventsResult · CalculatedInputValue · CalculatedMetricBackfill · CalculatedMetricBackfillAvailability · CalculatedMetricBackfillConnection · CalculatedMetricBackfillSkipCount · CalculatedSample · CalculatedSkipCount · Event · EventAnchorRef · EventSearchResults · FailedEvent · FailedEventDeviceCount · FailedEventReasonCount · FailedEventSearchResults · LocationEvent · LocationEventSearchResults · MeasurementBucket · MeasurementEvent · MeasurementEventSearchResults · SearchResultsPagination · StateChangeEvent · StateChangeEventSearchResults

AlertEvent​

object

A stored alert reported by a device (a message carrying several alerts produces one row each). This is an alert the device sent, not an alarm raised by a detection rule.

FieldTypeDescription
deviceTokenString!Token of the device that reported the alert.
eventTypeInt!Kind of event, as an integer; always 3 for an alert.
idID!Opaque identifier of this alert row, derived from its content. Serialized as a hexadecimal string.
levelInt!The alert's level, a non-negative integer as reported by the device.
messageStringThe alert's text, as sent by the device; an empty string when it sent none.
occurredTimeStringWhen the alert happened, as an RFC 3339 timestamp: the alert's own time where the device reported one, otherwise the time of the message that carried it.
sourceStringThe alert's source, as sent by the device; an empty string when it sent none.
typeString!The alert's type, as named by the device.

AlertEventSearchResults​

object

One page of alert events.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits within all matching alert events.
results[AlertEvent!]!The alert events on this page, newest first.

CalculatedEventsResult​

object

A draft formula evaluated over a device's stored readings. Inputs are read back from storage, which keeps a reading to inputDecimalPlaces decimal places, so a value here can differ from the one computed from the full-precision reading when it was recorded. Nothing here is stored.

FieldTypeDescription
computedInt!How many samples produced a value.
inputDecimalPlacesInt!How many decimal places stored inputs keep.
samples[CalculatedSample!]!Every evaluated sample in the range, oldest first.
skipped[CalculatedSkipCount!]!How many samples produced no value, by reason; only reasons that occurred are listed.

CalculatedInputValue​

object

One input of one evaluated sample, as the formula read it from storage.

FieldTypeDescription
keyString!The input's key.
valueString!The stored value the formula read, as text.

CalculatedMetricBackfill​

object

One calculated-metric backfill: a job that computes the metrics a published profile version defines for stored readings that have no value for them, and writes the missing values. It never changes a value that is already stored. Every counter is a Float, because a long job overflows a 32-bit Int, and every counter is exact across restarts.

FieldTypeDescription
alreadyPresentFloat!Pairs whose row already existed, so nothing was written.
cancelRequestedAtStringWhen a cancel was requested of a running job; null otherwise.
computedFloat!Pairs of a sample and a metric that produced a value or already held one.
createdAtString!When the job was accepted, an RFC 3339 timestamp in UTC.
createdByStringWho started it.
devicesDoneFloat!How many devices are finished.
devicesTotalFloatHow many devices the job covers; null until the first device page has been read.
failureStringWhy the job failed; null otherwise.
finishedAtStringWhen it reached a final status; null while active.
fromString!Start of the filled range, an RFC 3339 timestamp in UTC.
metricKeys[String!]!The metrics being filled.
profileTokenString!The token of the device profile whose version is filled.
profileVersionInt!The published version number whose formulas are filled.
progressFloatDevices done as a fraction of devicesTotal, 0 to 1; null while devicesTotal is unknown.
samplesFloat!Samples evaluated: the readings of one event at one instant.
skipped[CalculatedMetricBackfillSkipCount!]!Pairs that produced no value, by reason; only reasons that occurred are listed.
startedAtStringWhen the worker first took it; null while QUEUED.
statusCalculatedMetricBackfillStatus!Where the job stands.
storedInputPrecisionString!What the fill read: stored readings keep a fixed number of decimal places, so a value here can differ from one computed when the reading arrived.
toString!End of the filled range, an RFC 3339 timestamp in UTC.
tokenString!The job's token, unique within the tenant.
warnings[String!]!Notes about what the fill will and will not do, given when the job was accepted: a metric whose formula differs from an earlier version's, or one that reads an unselected metric that may be stored under an earlier formula.
windowsBeyondRetentionFloat!Device-batch and chunk-window pairs skipped because retention may drop the chunk.
windowsCompressedFloat!Device-batch and chunk-window pairs skipped because the chunk is compressed.
windowsRefreshedFloat!Windows whose rollup was refreshed.
writtenFloat!Rows written.

CalculatedMetricBackfillAvailability​

object

Whether this instance can run a calculated-metric backfill.

FieldTypeDescription
availableBoolean!True when a start is not refused for the instance's own state.
reasonStringWhy backfill is unavailable, for a person to read; null when available. It names the lever (the worker is switched off, or the event store has no connection to spare for it) and never the instance's settings or sizing, which are in the service's startup log.

CalculatedMetricBackfillConnection​

object

One page of backfill jobs, newest first.

FieldTypeDescription
nextCursorStringThe cursor to pass as after for the next page; null on the last page.
nodes[CalculatedMetricBackfill!]!The jobs on this page.

CalculatedMetricBackfillSkipCount​

object

How many (sample, metric) pairs a backfill skipped for one reason.

FieldTypeDescription
countFloat!How many pairs were skipped for it. A Float, because a long job overflows a 32-bit Int.
reasonString!The reason: a formula skip reason as in CalculatedSample.skippedReason, or ambiguous when a sample holds one of the formula's inputs twice with different values, so no single value can be chosen for it.

CalculatedSample​

object

One sample a draft formula was evaluated over: the readings of one stored event that share one instant. Exactly one of value and skippedReason is set.

FieldTypeDescription
eventIdString!Identifier of the stored event the readings belong to, as a hexadecimal string.
inputs[CalculatedInputValue!]!The inputs the sample held, as the formula read them.
occurredTimeString!When the readings were taken, as an RFC 3339 timestamp with fractional seconds.
skippedReasonStringWhy the formula produced no value for the sample: missing_input, invalid_input, non_finite, div_zero, overflow, range, unstorable or eval_error. Null when it produced one.
valueStringWhat the formula gave for the sample, as text; null when it produced no value.

CalculatedSkipCount​

object

How many samples a draft formula produced no value for, for one reason.

FieldTypeDescription
countInt!How many samples were skipped for it.
reasonString!The skip reason, as in CalculatedSample.skippedReason.

Event​

object

A stored event envelope: one message from one device, identified by the device's token. The readings it carries are stored separately and are read with locationEvents, measurementEvents and alertEvents.

FieldTypeDescription
altIdStringAlternate identifier supplied by the sender, which is part of the event's identity: it lets a device keep apart two otherwise identical events. Null if none was supplied.
anchors[EventAnchorRef!]!The relationship anchors recorded for this event. Empty for an event from a device that had no assignment when it arrived. A member whose access is limited to some customers sees only the anchors naming one of them.
deviceTokenString!Token of the device that sent the event.
eventTypeInt!Kind of event, as an integer: 0 new relationship, 1 location, 2 measurement, 3 alert, 4 state change, 5 command invocation, 6 command response.
idID!Opaque identifier of the event, derived from its content: the same event delivered twice has the same id. Serialized as a hexadecimal string.
occurredTimeStringWhen the event happened, as an RFC 3339 timestamp: the device's own time where it reported one, otherwise the time the platform received it.
processedTimeStringWhen the platform received the event, as an RFC 3339 timestamp. For events arriving on the platform's MQTT broker this is the time the broker stored the message; otherwise the time the ingest path took the event in.
sourceString!Identifier of the event source (inbound transport) that received the event.

EventAnchorRef​

object

One relationship anchor of an event: an entity the event is queryable by, such as the customer or area the device was assigned to when the event arrived.

FieldTypeDescription
tokenString!The anchored entity's token, unique within the tenant.
typeString!The entity class of the anchor: one of device, asset, area, customer or group.

EventSearchResults​

object

One page of event envelopes.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits within all matching events.
results[Event!]!The events on this page, newest first.

FailedEvent​

object

One record of an event the platform refused or could not store. The event itself is not kept here: a record says what was refused, for whom and why. Nothing here can be re-sent or replayed; fix the cause and the device's next event will be accepted.

To keep a misbehaving fleet from filling the list, at most 10 records are kept per device and reason in any hour; the rest are counted in suppressed on the newest of them, and past 1000 records an hour for one reason the remainder are counted on a single row with no deviceToken.

FieldTypeDescription
correlationString!The correlation id the failed event carried, for matching it to a log line.
deviceTokenStringThe device token the SENDER named. It is the sender's claim, not proof the device exists: for DEVICE_NOT_FOUND it names no device at all. Null when the record named none, and for the row that counts a reason's overflow.
errorString!What went wrong, in the platform's words. Bounded to 512 bytes.
eventTypeIntThe event type the sender named (see EventSearchCriteria.eventTypes), when there was one.
idID!An opaque identifier of this record, stable across requests. It carries no meaning.
occurredTimeString!When the platform recorded the failure (RFC 3339), not when the device sent the event.
overflowBoolean!True for the row that counts a reason's records beyond the 1000-an-hour bound.
payloadStatusFailedEventPayloadStatus!Whether the original event was kept and is still held on the failure stream; see FailedEventPayloadStatus.
reasonFailedEventReason!Why the event was refused.
reasonCodeInt!The reason's number, for a reason the enum calls UNKNOWN.
sourceAreaString!The part of the platform that refused the event.
suppressedInt!How many further records of this reason from this device the hourly bound folded into this one.

FailedEventDeviceCount​

object

One device's failures for a reason.

FieldTypeDescription
deviceTokenString!The token the sender named.
recordsInt!Records for this device, including those folded into a count.

FailedEventReasonCount​

object

One reason's line of the failure summary.

FieldTypeDescription
devices[FailedEventDeviceCount!]!The devices with the most records for this reason, most first (at most 10).
reasonFailedEventReason!The reason.
reasonCodeInt!The reason's number, for a reason the enum calls UNKNOWN.
recordsInt!Every record refused for this reason in the span, including those folded into a count.
suppressedInt!Of records, how many were folded into a count rather than kept as a row.

FailedEventSearchResults​

object

One page of failed-event records.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits within all matching records.
results[FailedEvent!]!The records on this page, newest first.

LocationEvent​

object

A stored location fix. Coordinates are WGS84 decimal degrees; every coordinate is optional because a device reports only what its receiver knows, and null means not reported (not 0).

FieldTypeDescription
accuracyFloatHorizontal accuracy of the fix in metres; null when not reported.
deviceTokenString!Token of the device that reported the fix.
elevationFloatElevation in metres; null when not reported.
eventTypeInt!Kind of event, as an integer; always 1 for a location event.
headingFloatHeading in degrees clockwise from true north, in the range 0 to 360 (360 excluded); null when not reported.
idID!Opaque identifier of this location row, derived from its content. Serialized as a hexadecimal string.
latitudeFloatLatitude in decimal degrees; null when not reported.
longitudeFloatLongitude in decimal degrees; null when not reported.
occurredTimeStringWhen the fix was taken, as an RFC 3339 timestamp: the sample's own time where the device reported one, otherwise the time of the message that carried it.
speedFloatGround speed in metres per second; null when not reported.

LocationEventSearchResults​

object

One page of location events.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits within all matching location events.
results[LocationEvent!]!The location events on this page, newest first.

MeasurementBucket​

object

Aggregated values of one measurement name over one time bucket. Every standard aggregate is returned so a single query can drive a chart under any aggregation.

FieldTypeDescription
avgFloatAverage of the bucket's values; null when the bucket holds no non-null values.
bucketStartString!Start of the bucket, as an RFC 3339 timestamp.
countInt!Number of non-null values in the bucket.
maxFloatLargest value in the bucket; null when the bucket holds no non-null values.
minFloatSmallest value in the bucket; null when the bucket holds no non-null values.
nameString!Name of the measurement the bucket aggregates.
sumFloatSum of the bucket's values; null when the bucket holds no non-null values.

MeasurementEvent​

object

A measurement: one named reading from a device (a message carrying several readings produces one row each). Returned by measurementEvents (stored rows) and measurementStream (live readings). Unit and data type are copied from the bound metric definition when the reading is stored, so the row describes itself and does not change if the definition is later edited.

FieldTypeDescription
classifierStringId of the metric definition the reading was bound to, as a decimal string; null for an undeclared measurement.
dataTypeStringData type copied from the bound metric definition; it tells a consumer how to read value, for example to render a 0/1 BOOLEAN as false/true. Null for an undeclared measurement.
deviceTokenString!Token of the device that reported the reading.
eventTypeInt!Kind of event, as an integer; always 2 for a measurement.
idID!Opaque identifier of this measurement row, derived from its content. Serialized as a hexadecimal string.
nameString!Name of the measurement, for example a metric key such as temperature.
occurredTimeStringWhen the reading was taken, as an RFC 3339 timestamp: the sample's own time where the device reported one, otherwise the time of the message that carried it.
unitStringUnit of measure copied from the bound metric definition; null for an undeclared measurement.
valueFloatThe numeric value of the reading. A stored measurement always has one, because a non-numeric reading is rejected and not stored; on measurementStream such a reading is delivered with a null value.

MeasurementEventSearchResults​

object

One page of measurement events.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits within all matching measurement events.
results[MeasurementEvent!]!The measurement events on this page, newest first.

SearchResultsPagination​

object

Where one page of search results sits within the full result set. Positions are 1-based and inclusive.

FieldTypeDescription
pageEndIntPosition of the last result of this page within the full result set (1-based, inclusive). Capped at totalRecords.
pageStartIntPosition of the first result of this page within the full result set (1-based).
totalRecordsIntNumber of records matching the criteria across all pages.

StateChangeEvent​

object

A stored presence transition of a device: the history behind its live connectivity state. One row per transition the device's transport reported, so it shows when the device connected, when it disconnected, and when the platform stopped trusting the transport to report for it.

FieldTypeDescription
deviceTokenString!Token of the device the transition belongs to.
eventTypeInt!Kind of event, as an integer; always 4 for a state change.
occurredTimeStringWhen the transition happened, as an RFC 3339 timestamp.
reasonStringWhy the transport reported the transition, when it said; null otherwise.
sessionIdString!The transport's connect epoch for the session the transition belongs to, as a decimal string. "0" when the transport reports none.
stateString!The transition: CONNECTED, DISCONNECTED, or DEMOTED. DEMOTED is not a connectivity edge: it records that the device was released back to inferred presence.

StateChangeEventSearchResults​

object

One page of presence transitions.

FieldTypeDescription
paginationSearchResultsPagination!Where this page sits within all matching transitions.
results[StateChangeEvent!]!The transitions on this page, newest first.

Input types​

CalculatedConstant · CalculatedInput · CalculatedMetricBackfillInput · EventAnchor · EventSearchCriteria · FailedEventSearchCriteria · MeasurementAggregationCriteria

CalculatedConstant​

input

One device constant a draft calculated-metric formula reads as device.name.

Input fieldTypeDescription
keyString!The constant's name, as the formula spells it after device..
valueString!The number the device's metadata holds under that name, as text such as 1.02.

CalculatedInput​

input

One input a draft calculated-metric formula reads: a measured metric's key and data type.

Input fieldTypeDescription
dataTypeString!The measured metric's data type: DOUBLE, INT or BOOLEAN.
keyString!The measured metric's key, as readings and the formula name it.

CalculatedMetricBackfillInput​

input

What to fill.

Input fieldTypeDescription
deviceTokens[String!]Only these devices, at most 1000; omit to fill every device of the profile.
fromString!Start of the range, an RFC 3339 timestamp. Not older than retention allows.
metricKeys[String!]The calculated metrics to fill. Omit to fill the metrics that are new in the version, those its previous published version did not calculate; a version with none then needs them named. A metric whose formula changed since an earlier version may be named, and is flagged in warnings.
profileTokenString!The token of the device profile.
toString!End of the range, an RFC 3339 timestamp, not in the future; after from, by at most 90 days.
versionIntThe published version to fill; omit for the active version. A draft is not a version.

EventAnchor​

input

A relationship anchor to filter events by: events recorded against this entity.

Input fieldTypeDescription
tokenString!Token of the entity, unique within the tenant.
typeString!Entity class: one of device, asset, area, customer or group. Any other value is an error.

EventSearchCriteria​

input

Filters and paging for event searches. All supplied filters must match. Results are newest first by occurred time.

Input fieldTypeDescription
anchorEventAnchorOnly events recorded against this entity.
deviceTokenStringOnly events from this device.
endTimeStringOnly events that occurred at or before this instant (inclusive), as an RFC 3339 timestamp. Omit for no upper bound. A value that is not RFC 3339 is an error.
eventTypes[Int!]Only events of these types, as integers (0 new relationship, 1 location, 2 measurement, 3 alert, 4 state change, 5 command invocation, 6 command response). An empty list applies no type filter.
pageNumberInt!Page to return, starting at 1; values below 1 are treated as 1.
pageSizeInt!Results per page. Values below 1 become 100; values above 1000 are capped at 1000.
startTimeStringOnly events that occurred at or after this instant (inclusive), as an RFC 3339 timestamp. Omit for no lower bound. A value that is not RFC 3339 is an error.

FailedEventSearchCriteria​

input

Filters and paging for the failed-event list. All supplied filters must match.

Input fieldTypeDescription
deviceTokenStringOnly failures for this device token, as the sender named it (a token longer than 128 bytes is matched as the platform stored it, cut to 128). The overflow row has no token and cannot be filtered for: "*" is refused with INVALID_VALUE.
pageNumberInt!Page to return, starting at 1; values below 1 are treated as 1.
pageSizeInt!Results per page. Values below 1 become 100; values above 100 are capped at 100.
reasonFailedEventReasonOnly failures for this reason. UNKNOWN selects every reason this version does not name.
sinceStringOnly failures recorded at or after this instant, an RFC 3339 timestamp. Defaults to, and is capped at, 31 days ago.
untilStringOnly failures recorded at or before this instant, an RFC 3339 timestamp.

MeasurementAggregationCriteria​

input

Filters for a server-side, time-bucketed measurement aggregation. The device, event type, time range and anchor filters work as in EventSearchCriteria, with an added filter on measurement name. startTime is required; a range that would produce more than 10,000 buckets, or a result of more than 50,000 rows (one per bucket per measurement name), is refused with LIMIT_EXCEEDED, so narrow the range, filter on a name or widen intervalSeconds.

Input fieldTypeDescription
anchorEventAnchorOnly measurements recorded against this entity. Anchored aggregations are computed from the individual readings.
deviceTokenStringOnly measurements from this device.
endTimeStringOnly readings that occurred at or before this instant, as an RFC 3339 timestamp. Omit to use the current time. Must not be before startTime. When the aggregation is served from one-minute summaries (see intervalSeconds) the bound is applied at whole-minute granularity, so readings later in the same minute are included.
eventTypes[Int!]Only readings whose event type is in this list, as integers. An empty list applies no type filter.
intervalSecondsInt!Width of each time bucket in seconds; must be 1 or more (smaller is an error). A width that is a multiple of 60 without an anchor filter is normally served from pre-computed one-minute summaries (an operator setting can turn that off); any other width is computed from the individual readings. Bucket boundaries are fixed instants shared by every query of the same width, not aligned to startTime.
nameStringOnly measurements with this name. Omit to aggregate every measurement name separately.
startTimeStringOnly readings that occurred at or after this instant, as an RFC 3339 timestamp. Required; omitting it is an error. When the aggregation is served from one-minute summaries (see intervalSeconds) the bound is applied at whole-minute granularity, so readings earlier in the same minute are included.

Enums​

CalculatedMetricBackfillStatus · FailedEventPayloadStatus · FailedEventReason

CalculatedMetricBackfillStatus​

enum

Where a calculated-metric backfill job stands. QUEUED and RUNNING are active; a tenant may have one active job. SUCCEEDED, CANCELLED and FAILED are final.

ValueDescription
QUEUEDAccepted and waiting for the worker.
RUNNINGThe worker is filling it.
SUCCEEDEDEvery device and window was filled or skipped, and the rollup was refreshed.
CANCELLEDCancelled. Rows already written stay.
FAILEDStopped on an error, named in failure. Rows already written stay; start a new job to resume.

FailedEventPayloadStatus​

enum

Whether the original event behind a failure record is still held on the platform's failure stream. The stream keeps records for a bounded time, the same bound that rolls its oldest records off unread, so a held original turns EXPIRED sooner or later; a record that is EXPIRED stays listed here and says so, rather than reading as an error or as empty. This API never returns the original, in any state.

ValueDescription
AVAILABLEThe stream still holds the original.
EXPIREDThe stream has discarded the original to make room; only this summary remains.
NOT_RETAINEDThe record never held an original (the platform could not read the message and kept nothing of it, or this is the overflow row); it will not become AVAILABLE or EXPIRED.
UNKNOWNThe stream could not be asked just now. None of the above is claimed.

FailedEventReason​

enum

Why the platform refused an event or could not store it. UNKNOWN is a reason this version of the API does not name: either none was given, or a newer part of the platform wrote one, and then reasonCode carries its number. A reason is never reported as a different one.

ValueDescription
INVALIDThe message could not be read at all.
API_CALL_FAILEDA platform service the event needed could not be reached, or storing the event failed.
DEVICE_NOT_FOUNDNo device has the token the sender named.
UNAUTHENTICATEDThe credential the device presented was missing or wrong.
DEVICE_DISABLEDThe device exists and an operator has disabled it.
NOT_GATEWAY_CHILDA gateway published for a device that is not assigned to it, or that does not exist.
INTEGRATION_ALIAS_MISMATCHAn integration's event named a device that no longer holds the alias it was resolved from.
DECODE_FAILEDA payload decoder refused an integration's uplink; the start of the error text names why (for example no_section or invalid_output).
UNKNOWNNo reason, or one this version does not name; see reasonCode.