| 1 | # List members via Netdata Cloud |
| 2 | |
| 3 | This guide is part of the [`query-netdata-cloud`](./SKILL.md) skill. |
| 4 | Read the [SKILL.md prerequisites](./SKILL.md#prerequisites) first. |
| 5 | |
| 6 | Members are Cloud-only. There is no agent-side equivalent. |
| 7 | |
| 8 | --- |
| 9 | |
| 10 | ## Endpoint |
| 11 | |
| 12 | `GET /api/v2/spaces/{spaceID}/members` -- list members of a space. |
| 13 | |
| 14 | ## Use the wrapper |
| 15 | |
| 16 | ```bash |
| 17 | source "$(git rev-parse --show-toplevel)/.agents/skills/query-netdata-agents/scripts/_lib.sh" |
| 18 | agents_load_env |
| 19 | |
| 20 | # All members of a space. |
| 21 | agents_query_cloud GET "/api/v2/spaces/$SPACE/members" |
| 22 | ``` |
| 23 | |
| 24 | ## Per-member response fields |
| 25 | |
| 26 | Verified live -- response is a JSON array, each entry: |
| 27 | |
| 28 | | Field | Description | |
| 29 | |---|---| |
| 30 | | `memberID` | UUID identifying the user's membership in this space (NOT the user's account id) | |
| 31 | | `accountID` | UUID identifying the user's Cloud account | |
| 32 | | `name` | Display name | |
| 33 | | `email` | Email | |
| 34 | | `avatarURL` | Avatar image URL (may be empty) | |
| 35 | | `role` | One of: `admin`, `manager`, `troubleshooter`, `observer`, `member`, `billing`, ... | |
| 36 | | `joinMethod` | How they joined: `invite`, `auto`, `sso`, ... | |
| 37 | | `joinedAt` | RFC3339 timestamp | |
| 38 | | `deactivated` | `true` if the membership has been deactivated (cannot view space until reactivated) | |
| 39 | |
| 40 | ## Common patterns |
| 41 | |
| 42 | ```bash |
| 43 | # Members by role. |
| 44 | agents_query_cloud GET "/api/v2/spaces/$SPACE/members" \ |
| 45 | | jq -r 'group_by(.role) | map({(.[0].role): length}) | add' |
| 46 | |
| 47 | # Active admins of a space. |
| 48 | agents_query_cloud GET "/api/v2/spaces/$SPACE/members" \ |
| 49 | | jq -r '.[] | select(.role=="admin" and (.deactivated|not)) | .name' |
| 50 | |
| 51 | # Resolve a user's display name from an accountID found elsewhere |
| 52 | # (e.g. in an alert-config audit field). |
| 53 | TARGET_ACCOUNT="<account-uuid>" |
| 54 | agents_query_cloud GET "/api/v2/spaces/$SPACE/members" \ |
| 55 | | jq -r --arg id "$TARGET_ACCOUNT" '.[] | select(.accountID==$id) | "\(.name) <\(.email)>"' |
| 56 | ``` |
| 57 | |
| 58 | ## Limits and gotchas |
| 59 | |
| 60 | - **Member visibility depends on the caller's role.** Observers |
| 61 | may not see all members. The response is filtered server-side |
| 62 | by what the caller is permitted to see. |
| 63 | - **`memberID` vs `accountID`**: the former is per-space (one |
| 64 | user gets a different `memberID` in each space); the latter is |
| 65 | the user's global Cloud account id and stays constant across |
| 66 | spaces. Use `accountID` when correlating across spaces. |
| 67 | - **Deactivated members still appear in the list** with |
| 68 | `deactivated:true`. Filter explicitly to exclude them. |
| 69 | - **Email and name are personal data.** Treat the response as |
| 70 | semi-sensitive: do not paste raw response bodies into |
| 71 | committed artifacts. Direct working output to |
| 72 | `<repo>/.local/audits/...` (gitignored). |
| 73 | |
| 74 | ## See also |
| 75 | |
| 76 | - [query-rooms.md](./query-rooms.md) -- room-level membership |
| 77 | (`isMember`, `permissions[]`, `member_count`). |
| 78 | - [query-feed.md](./query-feed.md) -- audit-feed events include |
| 79 | `user-create`, `space-user-added`, `space-user-removed`, |
| 80 | `user-space-permissions-changed`, `room-user-added`, ... use |
| 81 | the feed to track membership changes over time. |