Skip to content
logiccloud orchestrate

Query group statistics

POST
/api/v1/groups/query
curl --request POST \
  --url http://localhost:3000/api/v1/groups/query \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <X-API-Key>' \
  --data '{ "labelSelector": { "environment": "production", "region": "us-west" } }'

Retrieves statistics for devices matching a label selector.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
x-organization-id
string format: uuid

UUID of the organization (tenant) the request acts in. It selects the tenant and grants nothing: the server checks membership or an open tenant switch. Not needed for global operations. A malformed value returns 400. API keys are fixed to their own organization; another organization returns 403. The x-organization-source header grants nothing.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
labelSelector
required

Label selector: exact key/value pairs, all of which must match (AND). 1-20 entries, keys 1-253 and values up to 253 characters, string values only, no control characters. An empty selector is rejected with 400; use GET /api/v1/groups/stats for the whole fleet.

object
>= 1 properties <= 20 properties
key
additional properties
string
<= 253 characters
Example
{
  "environment": "production",
  "region": "us-west"
}

Responses

Section titled “Responses”

200

Section titled “200”

Group statistics retrieved successfully

Media typeapplication/json
object
total
required

Total number of matching devices

number
byStatus
required

Status breakdown of matching devices

object
online
required

Number of online devices

number
offline
required

Number of offline devices

number
pending
required

Number of pending devices

number
error
required

Number of devices in error state

number
labelSelector

The label selector used for filtering

object
key
additional properties
string
Example
{
  "total": 25,
  "byStatus": {
    "online": 45,
    "offline": 5,
    "pending": 2,
    "error": 1
  },
  "labelSelector": {
    "environment": "production"
  }
}

400

Section titled “400”

LabelSelector is missing, empty or not a valid label selector

401

Section titled “401”

Unauthorized

403

Section titled “403”

Forbidden — caller lacks required permission