Groups API

List groups

Get a list of visible groups for the authenticated user. When accessed without authentication, only public groups are returned.

By default, this request returns 20 results at a time because the API results are paginated.

When accessed without authentication, this endpoint also supports keyset pagination:

Parameters:

Attribute Type Required Description
skip_groups array of integers no Skip the group IDs passed
all_available boolean no Show all the groups you have access to (defaults to false for authenticated users, true for administrators); Attributes owned and min_access_level have precedence
search string no Return the list of authorized groups matching the search criteria
order_by string no Order groups by name, path, id, or similarity (if searching, introduced in GitLab 14.1). Default is name
sort string no Order groups in asc or desc order. Default is asc
statistics boolean no Include group statistics (administrators only)
with_custom_attributes boolean no Include custom attributes in response (administrators only)
owned boolean no Limit to groups explicitly owned by the current user
min_access_level integer no Limit to groups where current user has at least this access level
top_level_only boolean no Limit to top level groups, excluding all subgroups 
GET /groups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]

When adding the parameter statistics=true and the authenticated user is an administrator, additional group statistics are returned.

GET /groups?statistics=true

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level": "owner",
    "emails_disabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch_protection": 2,
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "statistics": {
      "storage_size": 363,
      "repository_size": 33,
      "wiki_size": 100,
      "lfs_objects_size": 123,
      "job_artifacts_size": 57,
      "pipeline_artifacts_size": 0,
      "packages_size": 0,
      "snippets_size": 50,
      "uploads_size": 0
    }
  }
]

You can search for groups by name or path, see below.

You can filter by custom attributes with:

GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value

List a group’s subgroups

Introduced in GitLab 10.3.

Get a list of visible direct subgroups in this group. When accessed without authentication, only public groups are returned.

By default, this request returns 20 results at a time because the API results are paginated.

Parameters:

Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group of the immediate parent group
skip_groups array of integers no Skip the group IDs passed
all_available boolean no Show all the groups you have access to (defaults to false for authenticated users, true for administrators); Attributes owned and min_access_level have precedence
search string no Return the list of authorized groups matching the search criteria. Only subgroup short paths are searched (not full paths)
order_by string no Order groups by name, path or id. Default is name
sort string no Order groups in asc or desc order. Default is asc
statistics boolean no Include group statistics (administrators only)
with_custom_attributes boolean no Include custom attributes in response (administrators only)
owned boolean no Limit to groups explicitly owned by the current user
min_access_level integer no Limit to groups where current user has at least this access level 
GET /groups/:id/subgroups

[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group",
    "visibility": "public",
    "share_with_group_lock": false,
    "require_two_factor_authentication": false,
    "two_factor_grace_period": 48,
    "project_creation_level": "developer",
    "auto_devops_enabled": null,
    "subgroup_creation_level"