GraphQL reference: device-state

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/device-state/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/device-state.graphql
Described	86 of 86 elements

Queries

assertedDeviceStates · deviceStates · deviceStatesByDeviceToken · deviceStatesByExternalId · latestLocation · latestLocations · latestMeasurements

assertedDeviceStates

Returns one page of the ASSERTED device states that belong to one event source, in ascending id order: the set an adapter reconciles against after a failover. Walk it with a cursor: pass the id of the last row of the previous page as afterId and keep asking until a page comes back with fewer rows than pageSize. A pageSize outside 1 to 1000 is an error, not adjusted. Requires state:read.

Returns [DeviceState!]!

Argument	Type	Description
activeOnly	Boolean!	Required. True returns only the devices the projection believes are online; false also returns the ones it believes are offline.
afterId	ID	Cursor: the id of the last row of the previous page. Omit for the first page. A non-numeric value is an error.
pageSize	Int!	Rows per page, between 1 and 1000 inclusive; anything else is an error.
source	String!	The event source, exactly as DeviceState.source reports it.

deviceStates

Searches device states, newest first, one page at a time. Requires state:read.

Returns DeviceStateSearchResults!

Argument	Type	Description
criteria	DeviceStateSearchCriteria!	Filter and page to return.

deviceStatesByDeviceToken

Returns the states of the given devices, in no particular order. Devices with no state yet are omitted. Requires state:read.

Returns [DeviceState!]!

Argument	Type	Description
deviceTokens	[String!]!	Tokens of the devices. More than 1000 is refused with LIMIT_EXCEEDED.

deviceStatesByExternalId

Returns the states of the devices carrying the given external ids, in no particular order. External ids that match nothing are omitted. Requires state:read.

Returns [DeviceState!]!

Argument	Type	Description
externalIds	[String!]!	External ids of the devices, as reported in DeviceState.externalId. More than 1000 is refused with LIMIT_EXCEEDED.

latestLocation

Returns the last-known position of one device, or null when it has never been located. Requires location:read.

Returns LatestLocation

Argument	Type	Description
deviceToken	String!	Token of the device.

latestLocations

Returns the last-known position of each of the given devices, ordered by device token. A device that has never been located is absent from the result. Requires location:read.

Returns [LatestLocation!]!

Argument	Type	Description
deviceTokens	[String!]!	Tokens of the devices. More than 1000 is refused with LIMIT_EXCEEDED.

latestMeasurements

Returns the current value of every measurement the device has reported, ordered by measurement name. Empty when the device has reported none. Requires state:read.

Returns [LatestMeasurement!]!

Argument	Type	Description
deviceToken	String!	Token of the device.

Mutations

demoteAssertedPresence

demoteAssertedPresence

Returns one page of an event source's ASSERTED device states to INFERRED presence, releasing that source's custody of them so the ordinary activity and inactivity rules apply again. It asserts nothing about connectivity: active and the connect, disconnect and alarm timestamps are unchanged. Walk the source by passing the previous result's lastId as afterId. Requires state:demote, which is separate from state:read.

Returns PresenceDemotionResult!

Argument	Type	Description
afterId	ID	Cursor: the lastId of the previous page. Omit for the first page. A non-numeric value is an error.
deviceTokens	[String!]	Optional narrowing within the source. Omit or null to demote the whole source; a non-empty list restricts to those devices (a token belonging to another source is not found, never demoted); an empty list demotes nothing; more than 1000 is refused with LIMIT_EXCEEDED.
limit	Int!	Rows to examine on this page, between 1 and 1000 inclusive; anything else is an error, not clamped.
reason	String!	Why the source is being demoted. Required and must not be blank; it is stamped onto every emitted event with your identity and logged, and is the only record of the change.
source	String!	The event source whose devices to demote, exactly as DeviceState.source reports it. Required and never inferred. A source nobody uses matches no rows.

Objects

DeviceState · DeviceStateSearchResults · LatestLocation · LatestMeasurement · PresenceDemotionResult · SearchResultsPagination

DeviceState

object

The live connectivity and activity state of one device, projected from its events. One row per device, created when the device first produces an event or presence signal.

Implements Model

Field	Type	Description
active	Boolean!	Whether the device is currently considered connected. For an INFERRED device it becomes true on activity and false when no activity arrives within inactivityTimeout. For an ASSERTED device it follows only the connect and disconnect signals of its event source.
createdAt	String	When the row was first created, as an RFC 3339 timestamp.
deletedAt	String	When the row was deleted, as an RFC 3339 timestamp. Deleted rows are not returned by this API, so this is null in practice.
deviceToken	String!	Token of the device this state belongs to.
externalId	String	The device's transport-native identity, copied from the events it sends; null when the device has no external id.
id	ID!	Server-assigned numeric identifier of the row, serialized as a string. Rows are addressed by device token; this id is also the cursor for assertedDeviceStates and demoteAssertedPresence.
inactivityAlarmTime	String	When the device was marked inactive for going silent, as an RFC 3339 timestamp. Cleared when the device becomes active again; null otherwise.
inactivityTimeout	Int!	Seconds without activity after which an INFERRED device is marked inactive. New devices start at 600; a stored value of 0 or less is treated as that default.
lastActivityTime	String	Time of the most recent event from the device, as an RFC 3339 timestamp; null if none. Taken from the event's own occurrence time, so an older event delivered late does not move it backwards.
lastConnectTime	String	When the device was last considered to have connected, as an RFC 3339 timestamp; null if it has not.
lastDisconnectTime	String	When the device was last considered to have disconnected, as an RFC 3339 timestamp. For an INFERRED device this is the moment the inactivity check marked it inactive, not the time of its last event. Null if it has not disconnected.
presenceSource	String!	How presence is decided: INFERRED (from activity and the inactivity timeout) or ASSERTED (the event source states connect and disconnect explicitly, and activity alone cannot change it).
presenceTime	String	Time of the last applied presence transition, as an RFC 3339 timestamp; null until one has been applied.
sessionId	String!	Ordering epoch of the last applied presence transition, serialized as a string because it is a nanosecond-scale integer too large for a GraphQL Int. "0" until the first presence signal.
source	String	The event source that last drove this device; null before the device has produced an event carrying one. MQTT and HTTP report the event source's own configured id (for example mqtt1), LwM2M reports lwm2m, and Sparkplug reports sparkplug:{hostId}. To classify a device by transport, cut at the first ':' and compare that part, because the first two forms are operator-chosen. Pass this value exactly as reported when you need a source argument elsewhere.
updatedAt	String	When the row was last modified, as an RFC 3339 timestamp.

DeviceStateSearchResults

object

One page of device states.

Field	Type	Description
pagination	SearchResultsPagination!	Where this page sits within all matching device states.
results	[DeviceState!]!	The device states on this page.

LatestLocation

object

The last-known position of a device: the "where is it right now?" view that sits beside the append-only location history. One row per device. Coordinates are WGS84 decimal degrees; elevation and accuracy are in metres, speed in metres per second, heading in degrees clockwise from true north. Reading it requires location:read, which is separate from state:read.

Implements Model

Field	Type	Description
accuracy	Float	Accuracy of the fix in metres; null when not reported.
createdAt	String	When the row was first created, as an RFC 3339 timestamp.
deletedAt	String	When the row was deleted, as an RFC 3339 timestamp. Deleted rows are not returned by this API, so this is null in practice.
deviceToken	String!	Token of the device the position belongs to.
elevation	Float	Elevation in metres above the ellipsoid (not mean sea level); null when not reported.
heading	Float	Heading in degrees clockwise from true north, in the range 0 to 360 (360 excluded); null when not reported.
id	ID!	Server-assigned numeric identifier of the row, serialized as a string. Rows are addressed by device token.
latitude	Float	Latitude in decimal degrees (WGS84, EPSG:4326); null when the fix did not report it. Null is not the same as 0.
longitude	Float	Longitude in decimal degrees (WGS84, EPSG:4326); null when the fix did not report it. Null is not the same as 0.
occurredTime	String!	When the fix was taken, as an RFC 3339 timestamp. An older fix delivered late does not replace a newer stored one.
speed	Float	Speed in metres per second; null when not reported.
updatedAt	String	When the row was last modified, as an RFC 3339 timestamp.

LatestMeasurement

object

The most recent value of one named measurement for a device: the live "what is it now?" view that sits beside the append-only measurement history. One row per device and measurement name.

Implements Model

Field	Type	Description
classifier	Int	Id of the metric definition the reading was bound to; null for a measurement with no definition.
createdAt	String	When the row was first created, as an RFC 3339 timestamp.
dataType	String	Data type copied from the bound metric definition (it lets a consumer render a 0/1 BOOLEAN value as false/true); null for an undeclared measurement.
deletedAt	String	When the row was deleted, as an RFC 3339 timestamp. Deleted rows are not returned by this API, so this is null in practice.
deviceToken	String!	Token of the device the reading belongs to.
id	ID!	Server-assigned numeric identifier of the row, serialized as a string. Rows are addressed by device token.
name	String!	Name of the measurement, for example a metric name such as temperature.
occurredTime	String!	When the reading was taken, as an RFC 3339 timestamp. An older reading delivered late does not replace a newer stored one.
unit	String	Unit of measure copied from the bound metric definition; null for an undeclared measurement.
updatedAt	String	When the row was last modified, as an RFC 3339 timestamp.
value	Float	The numeric value of the most recent reading. Only numeric readings are stored, so in practice this is always set.

PresenceDemotionResult

object

The outcome of one page of a presence demotion.

Field	Type	Description
demoted	Int!	How many demotion events were published, handing those devices back to inferred presence. The events are applied asynchronously.
lastId	ID	Id of the last row scanned: pass it as afterId on the next call. Null when the page was empty.
scanned	Int!	How many ASSERTED rows this page examined. Keep walking while it equals the limit you asked for; stop on the first page that comes back short. Do not use demoted as the stop signal.
skipped	Int!	Rows this page examined but could not release, which is scanned minus demoted. A row is skipped when it holds no presence time, or when its presence time is not in the past. A page that skips everything is a signal, not a failure.

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.

Interfaces

Model

Model

interface

Fields common to every stored row.

Field	Type	Description
createdAt	String	When the row was first created, as an RFC 3339 timestamp.
deletedAt	String	When the row was deleted, as an RFC 3339 timestamp. Deleted rows are not returned by this API, so this is null in practice.
id	ID!	Server-assigned numeric identifier of the row, serialized as a string. Rows are addressed by device token.
updatedAt	String	When the row was last modified, as an RFC 3339 timestamp.

Input types

DeviceStateSearchCriteria

DeviceStateSearchCriteria

input

Filter and paging for searching device states. Results are newest first (by row creation). To look up specific devices use deviceStatesByDeviceToken.

Input field	Type	Description
active	Boolean	Only devices whose active flag equals this value. Omit to include both.
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.