Presence API

List online users

GET /v2/utilities/presence

Returns every user with at least one online session in your organization. Optionally filter to users subscribed to a specific topic.

Parameters

Parameter	Type	Required	Description
`topic`	string	No	Return only users subscribed to this topic. Wildcards `+` and `#` are matched.

Example

curl "https://api.cloudsignal.app/v2/utilities/presence?topic=chat/lobby" \
  -H "X-Secret-Key: <YOUR_SECRET_KEY>"

Response

{
  "online_count": 2,
  "users": [
    {
      "username": "alice",
      "display_name": "Alice Martin",
      "client_id": "client-abc",
      "peer_host": "203.0.113.42",
      "connected_since": "2026-03-27T10:00:00Z",
      "subscribed_topics": ["chat/lobby"]
    },
    {
      "username": "bob",
      "display_name": null,
      "client_id": "client-def",
      "peer_host": "203.0.113.77",
      "connected_since": "2026-03-27T10:05:00Z",
      "subscribed_topics": ["chat/lobby", "chat/dms/bob"]
    }
  ]
}

Response fields

Field	Type	Description
`online_count`	integer	Number of online users returned.
`users[].username`	string	MQTT username, without the organization suffix.
`users[].display_name`	string \| null	Human-readable name if one is set, otherwise null.
`users[].client_id`	string	MQTT client ID of the session.
`users[].peer_host`	string \| null	Client IP address.
`users[].connected_since`	string \| null	Connection time as an ISO 8601 UTC timestamp.
`users[].subscribed_topics`	string[]	Topics this session is subscribed to.

A user with more than one online connection appears once per session, each with its own client_id.

Check a specific user

GET /v2/utilities/presence/{username}

Returns the online status of a single user, along with details for each active session.

Example

curl "https://api.cloudsignal.app/v2/utilities/presence/alice" \
  -H "X-Secret-Key: <YOUR_SECRET_KEY>"

Response

{
  "username": "alice",
  "display_name": "Alice Martin",
  "is_online": true,
  "session_count": 1,
  "sessions": [
    {
      "client_id": "client-abc",
      "peer_host": "203.0.113.42",
      "peer_port": 54122,
      "connected_since": "2026-03-27T10:00:00Z",
      "protocol": "5",
      "subscribed_topics": ["chat/lobby"]
    }
  ]
}

Response fields

Field	Type	Description
`username`	string	MQTT username that was queried.
`display_name`	string \| null	Human-readable name if one is set, otherwise null.
`is_online`	boolean	True if the user has at least one active session.
`session_count`	integer	Number of active sessions for the user.
`sessions[].client_id`	string	MQTT client ID of the session.
`sessions[].peer_host`	string \| null	Client IP address.
`sessions[].peer_port`	integer \| null	Client source port.
`sessions[].connected_since`	string \| null	Connection time as an ISO 8601 UTC timestamp.
`sessions[].protocol`	string \| null	MQTT protocol version reported by the client.
`sessions[].subscribed_topics`	string[]	Topics this session is subscribed to.

When the user has no active sessions, is_online is false, session_count is 0, and sessions is an empty array.

On this page