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.
| Endpoint | https://<your-host>/api/event-management/graphql |
| Auth plane | tenant — 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 with | tenant access token |
| Schema file | /schema/event-management.graphql |
| Described | 258 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!
| Argument | Type | Description |
|---|---|---|
criteria | EventSearchCriteria! | 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!]!
| Argument | Type | Description |
|---|---|---|
criteria | MeasurementAggregationCriteria! | 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!
| Argument | Type | Description |
|---|---|---|
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. |
dataType | String! | The calculated metric's data type: DOUBLE, INT or BOOLEAN. |
deviceToken | String! | Token of the device whose readings to evaluate. |
expression | String! | The formula, as written on the calculated metric. |
from | String! | 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. |
maxValue | Float | Largest value the metric may take; a result above it is skipped as range. |
minValue | Float | Smallest value the metric may take; a result below it is skipped as range. |
to | String! | 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
| Argument | Type | Description |
|---|---|---|
token | String! | 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!
| Argument | Type | Description |
|---|---|---|
after | String | The nextCursor of the previous page; omit for the first page. |
first | Int | Page size, 1 to 100; defaults to 25. |
profileToken | String | Only 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!
| Argument | Type | Description |
|---|---|---|
criteria | EventSearchCriteria! | 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!
| Argument | Type | Description |
|---|---|---|
deviceToken | String! | The device token, as the sender names it. |
since | String! | 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!]!
| Argument | Type | Description |
|---|---|---|
since | String! | 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!
| Argument | Type | Description |
|---|---|---|
criteria | FailedEventSearchCriteria! | 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!
| Argument | Type | Description |
|---|---|---|
criteria | EventSearchCriteria! | 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!
| Argument | Type | Description |
|---|---|---|
criteria | EventSearchCriteria! | 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!
| Argument | Type | Description |
|---|---|---|
criteria | EventSearchCriteria! | 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!
| Argument | Type | Description |
|---|---|---|
token | String! | 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!
| Argument | Type | Description |
|---|---|---|
input | CalculatedMetricBackfillInput! | The profile, version, metrics, range and devices to fill. |
Subscriptions
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!
| Argument | Type | Description |
|---|---|---|
deviceToken | String | Only measurements from this device. Omit for all devices. |
name | String | Only 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.
| Field | Type | Description |
|---|---|---|
deviceToken | String! | Token of the device that reported the alert. |
eventType | Int! | Kind of event, as an integer; always 3 for an alert. |
id | ID! | Opaque identifier of this alert row, derived from its content. Serialized as a hexadecimal string. |
level | Int! | The alert's level, a non-negative integer as reported by the device. |
message | String | The alert's text, as sent by the device; an empty string when it sent none. |
occurredTime | String | When 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. |
source | String | The alert's source, as sent by the device; an empty string when it sent none. |
type | String! | The alert's type, as named by the device. |
AlertEventSearchResults
object
One page of alert events.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | 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.
| Field | Type | Description |
|---|---|---|
computed | Int! | How many samples produced a value. |
inputDecimalPlaces | Int! | 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.
| Field | Type | Description |
|---|---|---|
key | String! | The input's key. |
value | String! | 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.
| Field | Type | Description |
|---|---|---|
alreadyPresent | Float! | Pairs whose row already existed, so nothing was written. |
cancelRequestedAt | String | When a cancel was requested of a running job; null otherwise. |
computed | Float! | Pairs of a sample and a metric that produced a value or already held one. |
createdAt | String! | When the job was accepted, an RFC 3339 timestamp in UTC. |
createdBy | String | Who started it. |
devicesDone | Float! | How many devices are finished. |
devicesTotal | Float | How many devices the job covers; null until the first device page has been read. |
failure | String | Why the job failed; null otherwise. |
finishedAt | String | When it reached a final status; null while active. |
from | String! | Start of the filled range, an RFC 3339 timestamp in UTC. |
metricKeys | [String!]! | The metrics being filled. |
profileToken | String! | The token of the device profile whose version is filled. |
profileVersion | Int! | The published version number whose formulas are filled. |
progress | Float | Devices done as a fraction of devicesTotal, 0 to 1; null while devicesTotal is unknown. |
samples | Float! | 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. |
startedAt | String | When the worker first took it; null while QUEUED. |
status | CalculatedMetricBackfillStatus! | Where the job stands. |
storedInputPrecision | String! | 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. |
to | String! | End of the filled range, an RFC 3339 timestamp in UTC. |
token | String! | 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. |
windowsBeyondRetention | Float! | Device-batch and chunk-window pairs skipped because retention may drop the chunk. |
windowsCompressed | Float! | Device-batch and chunk-window pairs skipped because the chunk is compressed. |
windowsRefreshed | Float! | Windows whose rollup was refreshed. |
written | Float! | Rows written. |
CalculatedMetricBackfillAvailability
object
Whether this instance can run a calculated-metric backfill.
| Field | Type | Description |
|---|---|---|
available | Boolean! | True when a start is not refused for the instance's own state. |
reason | String | Why 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.
| Field | Type | Description |
|---|---|---|
nextCursor | String | The 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.
| Field | Type | Description |
|---|---|---|
count | Float! | How many pairs were skipped for it. A Float, because a long job overflows a 32-bit Int. |
reason | String! | 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.
| Field | Type | Description |
|---|---|---|
eventId | String! | 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. |
occurredTime | String! | When the readings were taken, as an RFC 3339 timestamp with fractional seconds. |
skippedReason | String | Why 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. |
value | String | What 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.
| Field | Type | Description |
|---|---|---|
count | Int! | How many samples were skipped for it. |
reason | String! | 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.
| Field | Type | Description |
|---|---|---|
altId | String | Alternate 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. |
deviceToken | String! | Token of the device that sent the event. |
eventType | Int! | Kind of event, as an integer: 0 new relationship, 1 location, 2 measurement, 3 alert, 4 state change, 5 command invocation, 6 command response. |
id | ID! | Opaque identifier of the event, derived from its content: the same event delivered twice has the same id. Serialized as a hexadecimal string. |
occurredTime | String | When the event happened, as an RFC 3339 timestamp: the device's own time where it reported one, otherwise the time the platform received it. |
processedTime | String | When 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. |
source | String! | 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.
| Field | Type | Description |
|---|---|---|
token | String! | The anchored entity's token, unique within the tenant. |
type | String! | The entity class of the anchor: one of device, asset, area, customer or group. |
EventSearchResults
object
One page of event envelopes.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | 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.
| Field | Type | Description |
|---|---|---|
correlation | String! | The correlation id the failed event carried, for matching it to a log line. |
deviceToken | String | The 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. |
error | String! | What went wrong, in the platform's words. Bounded to 512 bytes. |
eventType | Int | The event type the sender named (see EventSearchCriteria.eventTypes), when there was one. |
id | ID! | An opaque identifier of this record, stable across requests. It carries no meaning. |
occurredTime | String! | When the platform recorded the failure (RFC 3339), not when the device sent the event. |
overflow | Boolean! | True for the row that counts a reason's records beyond the 1000-an-hour bound. |
payloadStatus | FailedEventPayloadStatus! | Whether the original event was kept and is still held on the failure stream; see FailedEventPayloadStatus. |
reason | FailedEventReason! | Why the event was refused. |
reasonCode | Int! | The reason's number, for a reason the enum calls UNKNOWN. |
sourceArea | String! | The part of the platform that refused the event. |
suppressed | Int! | 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.
| Field | Type | Description |
|---|---|---|
deviceToken | String! | The token the sender named. |
records | Int! | Records for this device, including those folded into a count. |
FailedEventReasonCount
object
One reason's line of the failure summary.
| Field | Type | Description |
|---|---|---|
devices | [FailedEventDeviceCount!]! | The devices with the most records for this reason, most first (at most 10). |
reason | FailedEventReason! | The reason. |
reasonCode | Int! | The reason's number, for a reason the enum calls UNKNOWN. |
records | Int! | Every record refused for this reason in the span, including those folded into a count. |
suppressed | Int! | Of records, how many were folded into a count rather than kept as a row. |
FailedEventSearchResults
object
One page of failed-event records.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | 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).
| Field | Type | Description |
|---|---|---|
accuracy | Float | Horizontal accuracy of the fix in metres; null when not reported. |
deviceToken | String! | Token of the device that reported the fix. |
elevation | Float | Elevation in metres; null when not reported. |
eventType | Int! | Kind of event, as an integer; always 1 for a location event. |
heading | Float | Heading in degrees clockwise from true north, in the range 0 to 360 (360 excluded); null when not reported. |
id | ID! | Opaque identifier of this location row, derived from its content. Serialized as a hexadecimal string. |
latitude | Float | Latitude in decimal degrees; null when not reported. |
longitude | Float | Longitude in decimal degrees; null when not reported. |
occurredTime | String | When 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. |
speed | Float | Ground speed in metres per second; null when not reported. |
LocationEventSearchResults
object
One page of location events.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | 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.
| Field | Type | Description |
|---|---|---|
avg | Float | Average of the bucket's values; null when the bucket holds no non-null values. |
bucketStart | String! | Start of the bucket, as an RFC 3339 timestamp. |
count | Int! | Number of non-null values in the bucket. |
max | Float | Largest value in the bucket; null when the bucket holds no non-null values. |
min | Float | Smallest value in the bucket; null when the bucket holds no non-null values. |
name | String! | Name of the measurement the bucket aggregates. |
sum | Float | Sum 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.
| Field | Type | Description |
|---|---|---|
classifier | String | Id of the metric definition the reading was bound to, as a decimal string; null for an undeclared measurement. |
dataType | String | Data 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. |
deviceToken | String! | Token of the device that reported the reading. |
eventType | Int! | Kind of event, as an integer; always 2 for a measurement. |
id | ID! | Opaque identifier of this measurement row, derived from its content. Serialized as a hexadecimal string. |
name | String! | Name of the measurement, for example a metric key such as temperature. |
occurredTime | String | When 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. |
unit | String | Unit of measure copied from the bound metric definition; null for an undeclared measurement. |
value | Float | The 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.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | 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.
| Field | Type | Description |
|---|---|---|
pageEnd | Int | Position of the last result of this page within the full result set (1-based, inclusive). Capped at totalRecords. |
pageStart | Int | Position of the first result of this page within the full result set (1-based). |
totalRecords | Int | Number 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.
| Field | Type | Description |
|---|---|---|
deviceToken | String! | Token of the device the transition belongs to. |
eventType | Int! | Kind of event, as an integer; always 4 for a state change. |
occurredTime | String | When the transition happened, as an RFC 3339 timestamp. |
reason | String | Why the transport reported the transition, when it said; null otherwise. |
sessionId | String! | The transport's connect epoch for the session the transition belongs to, as a decimal string. "0" when the transport reports none. |
state | String! | 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.
| Field | Type | Description |
|---|---|---|
pagination | SearchResultsPagination! | 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 field | Type | Description |
|---|---|---|
key | String! | The constant's name, as the formula spells it after device.. |
value | String! | 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 field | Type | Description |
|---|---|---|
dataType | String! | The measured metric's data type: DOUBLE, INT or BOOLEAN. |
key | String! | The measured metric's key, as readings and the formula name it. |
CalculatedMetricBackfillInput
input
What to fill.
| Input field | Type | Description |
|---|---|---|
deviceTokens | [String!] | Only these devices, at most 1000; omit to fill every device of the profile. |
from | String! | 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. |
profileToken | String! | The token of the device profile. |
to | String! | End of the range, an RFC 3339 timestamp, not in the future; after from, by at most 90 days. |
version | Int | The 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 field | Type | Description |
|---|---|---|
token | String! | Token of the entity, unique within the tenant. |
type | String! | 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 field | Type | Description |
|---|---|---|
anchor | EventAnchor | Only events recorded against this entity. |
deviceToken | String | Only events from this device. |
endTime | String | Only 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. |
pageNumber | Int! | Page to return, starting at 1; values below 1 are treated as 1. |
pageSize | Int! | Results per page. Values below 1 become 100; values above 1000 are capped at 1000. |
startTime | String | Only 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 field | Type | Description |
|---|---|---|
deviceToken | String | Only 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. |
pageNumber | Int! | Page to return, starting at 1; values below 1 are treated as 1. |
pageSize | Int! | Results per page. Values below 1 become 100; values above 100 are capped at 100. |
reason | FailedEventReason | Only failures for this reason. UNKNOWN selects every reason this version does not name. |
since | String | Only failures recorded at or after this instant, an RFC 3339 timestamp. Defaults to, and is capped at, 31 days ago. |
until | String | Only 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 field | Type | Description |
|---|---|---|
anchor | EventAnchor | Only measurements recorded against this entity. Anchored aggregations are computed from the individual readings. |
deviceToken | String | Only measurements from this device. |
endTime | String | Only 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. |
intervalSeconds | Int! | 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. |
name | String | Only measurements with this name. Omit to aggregate every measurement name separately. |
startTime | String | Only 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.
| Value | Description |
|---|---|
QUEUED | Accepted and waiting for the worker. |
RUNNING | The worker is filling it. |
SUCCEEDED | Every device and window was filled or skipped, and the rollup was refreshed. |
CANCELLED | Cancelled. Rows already written stay. |
FAILED | Stopped 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.
| Value | Description |
|---|---|
AVAILABLE | The stream still holds the original. |
EXPIRED | The stream has discarded the original to make room; only this summary remains. |
NOT_RETAINED | The 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. |
UNKNOWN | The 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.
| Value | Description |
|---|---|
INVALID | The message could not be read at all. |
API_CALL_FAILED | A platform service the event needed could not be reached, or storing the event failed. |
DEVICE_NOT_FOUND | No device has the token the sender named. |
UNAUTHENTICATED | The credential the device presented was missing or wrong. |
DEVICE_DISABLED | The device exists and an operator has disabled it. |
NOT_GATEWAY_CHILD | A gateway published for a device that is not assigned to it, or that does not exist. |
INTEGRATION_ALIAS_MISMATCH | An integration's event named a device that no longer holds the alias it was resolved from. |
DECODE_FAILED | A payload decoder refused an integration's uplink; the start of the error text names why (for example no_section or invalid_output). |
UNKNOWN | No reason, or one this version does not name; see reasonCode. |