= groups()
:description: Returns all groups defined on the server as a list of ECMGroup objects (mng.GetGroupList). Optionally filtered by a user GUID.
:keywords: groups, mng.GetGroupList, ECMGroup, GUID
:page-tags: api, security

Returns all groups defined on the server.

== Signature

[tabs]
====
Sync::
+
[source,python]
----
ecm.security.groups() -> list[ECMGroup]
----

Async::
+
[source,python]
----
await ecm.security.groups() -> list[ECMGroup]
----
====

== Return value

List of `ECMGroup` instances. Empty list when no groups exist.

=== ECMGroup fields

[cols="1,1,3"]
|===
|Field |Type |Description

|`id`
|`int`
|Numeric group ID.

|`name`
|`str`
|Name of the group.

|`guid`
|`str`
|Globally unique identifier of the group.

|`profile_user_id`
|`int`
|ID of the profile user assigned to the group. `-1` if no profile user is assigned.

|`description`
|`str`
|Optional description of the group.
|===

== Examples

=== List all groups

[tabs]
====
Sync::
+
[source,python]
----
groups = ecm.security.groups()
for group in groups:
    print(group.name, group.guid)
----

Async::
+
[source,python]
----
groups = await ecm.security.groups()
for group in groups:
    print(group.name, group.guid)
----
====

=== Find a group by name

[tabs]
====
Sync::
+
[source,python]
----
groups = ecm.security.groups()
admins = next((g for g in groups if g.name == "Administrators"), None)
----

Async::
+
[source,python]
----
groups = await ecm.security.groups()
admins = next((g for g in groups if g.name == "Administrators"), None)
----
====

== See also

* xref:api/security/group.adoc[group()] — Retrieve attributes of a single group
* xref:api/security/group_members.adoc[group_members()] — Retrieve members of a group
* xref:api/security/user_groups.adoc[user_groups()] — Groups of a specific user
