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	99 of 99 elements

Queries

alertEvents · bucketedMeasurements · events · locationEvents · measurementEvents

alertEvents

Searches stored device alerts, newest first by occurred time, one page at a time. Requires event:read.

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.

Returns [MeasurementBucket!]!

Argument	Type	Description
criteria	MeasurementAggregationCriteria!	Filters and bucket width.

events

Searches stored event envelopes, newest first by occurred time, one page at a time. Requires event:read.

Returns EventSearchResults!

Argument	Type	Description
criteria	EventSearchCriteria!	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.

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.

Returns MeasurementEventSearchResults!

Argument	Type	Description
criteria	EventSearchCriteria!	Filters and page to return.

Mutations

_empty

_empty

Placeholder that does nothing and always returns null. This service has no mutations: events are written by the ingest pipeline, not through the API.

Returns Boolean

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.

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 · Event · EventAnchorRef · EventSearchResults · LocationEvent · LocationEventSearchResults · MeasurementBucket · MeasurementEvent · MeasurementEventSearchResults · SearchResultsPagination

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.

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.
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.

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.

Input types

EventAnchor · EventSearchCriteria · MeasurementAggregationCriteria

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.

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.