[Skip to main content](https://docs.gitlab.com/api/groups/#skipTarget) [Go to GitLab Docs homepage](https://docs.gitlab.com/)
`/`
[What's new?](https://about.gitlab.com/releases/whats-new/)
English
  * Language
  * English
  * 日本語


v18.10
  *     * [18.10 (not yet released)](https://docs.gitlab.com/api/groups/)
  *     * [18.9 (recently released)](https://docs.gitlab.com/18.9/api/groups/)
    * [18.8](https://docs.gitlab.com/18.8/api/groups/)
    * [18.7](https://archives.docs.gitlab.com/18.7/api/groups/)
  *     * [17.11](https://archives.docs.gitlab.com/17.11/api/groups/)
    * [16.11](https://archives.docs.gitlab.com/16.11/ee/api/groups.html)
  *     * [Archives](https://docs.gitlab.com/archives)


Select theme and layout
  * Light mode
  * Dark mode
  * Auto


  * Fixed width
  * Fluid width


[What's new?](https://about.gitlab.com/releases/whats-new/) [Get free trial](https://gitlab.com/-/trial_registrations/new?glm_source=docs.gitlab.com&amp;glm_content=navigation-cta-docs)
Toggle menu
  * [Use GitLab](https://docs.gitlab.com/user/)
  * [GitLab Duo](https://docs.gitlab.com/user/gitlab_duo/)
  * [Extend](https://docs.gitlab.com/api/)
  * [Install](https://docs.gitlab.com/install/)
  * [Administer](https://docs.gitlab.com/administration/)
  * [Subscribe](https://docs.gitlab.com/subscriptions/)
  * [Contribute](https://docs.gitlab.com/development/)
  * [Solutions](https://docs.gitlab.com/solutions/)


Select a topicUse GitLab GitLab Duo Extend Install Administer Subscribe Contribute Solutions
[Getting started](https://docs.gitlab.com/api/get_started/get_started_extending/)
[Tutorials](https://docs.gitlab.com/tutorials/develop/)
[Integrations](https://docs.gitlab.com/integration/)
[Webhooks](https://docs.gitlab.com/user/project/integrations/webhooks/)
[REST API](https://docs.gitlab.com/api/rest/)
[Resources](https://docs.gitlab.com/api/api_resources/)
[.gitignore (templates)](https://docs.gitlab.com/api/templates/gitignores/)
[.gitlab-ci.yml (templates)](https://docs.gitlab.com/api/templates/gitlab_ci_ymls/)
[Access requests](https://docs.gitlab.com/api/access_requests/)
[Agent for Kubernetes](https://docs.gitlab.com/api/cluster_agents/)
[AI Catalog admin](https://docs.gitlab.com/api/admin/ai_catalog/)
[Alert management](https://docs.gitlab.com/api/alert_management_alerts/)
[Application appearance](https://docs.gitlab.com/api/appearance/)
[Application settings](https://docs.gitlab.com/api/settings/)
[Application statistics](https://docs.gitlab.com/api/statistics/)
[Applications](https://docs.gitlab.com/api/applications/)
[Attestations](https://docs.gitlab.com/api/attestations/)
[Audit events](https://docs.gitlab.com/api/audit_events/)
[Avatar](https://docs.gitlab.com/api/avatar/)
[Branches](https://docs.gitlab.com/api/branches/)
[Broadcast messages](https://docs.gitlab.com/api/broadcast_messages/)
[Cluster discovery (certificate-based) (deprecated)](https://docs.gitlab.com/api/cluster_discovery/)
[Code Suggestions](https://docs.gitlab.com/api/code_suggestions/)
[Commits](https://docs.gitlab.com/api/commits/)
[Compliance and policy settings](https://docs.gitlab.com/api/compliance_policy_settings/)
[Composer](https://docs.gitlab.com/api/packages/composer/)
[Conan v1](https://docs.gitlab.com/api/packages/conan_v1/)
[Conan v2](https://docs.gitlab.com/api/packages/conan_v2/)
[Container registry](https://docs.gitlab.com/api/container_registry/)
[Container repository protection rules](https://docs.gitlab.com/api/container_repository_protection_rules/)
[Container registry protection tag rules](https://docs.gitlab.com/api/container_registry_protection_tag_rules/)
[Container virtual registry](https://docs.gitlab.com/api/container_virtual_registries/)
[Custom attributes](https://docs.gitlab.com/api/custom_attributes/)
[Database migrations](https://docs.gitlab.com/api/database_migrations/)
[Data management](https://docs.gitlab.com/api/admin/data_management/)
[Debian](https://docs.gitlab.com/api/packages/debian/)
[Debian group distributions](https://docs.gitlab.com/api/packages/debian_group_distributions/)
[Debian project distributions](https://docs.gitlab.com/api/packages/debian_project_distributions/)
[Dependencies](https://docs.gitlab.com/api/dependencies/)
[Dependency list export](https://docs.gitlab.com/api/dependency_list_export/)
[Dependency Proxy](https://docs.gitlab.com/api/dependency_proxy/)
[Deploy keys](https://docs.gitlab.com/api/deploy_keys/)
[Deploy tokens](https://docs.gitlab.com/api/deploy_tokens/)
[Deployments](https://docs.gitlab.com/api/deployments/)
[Discussions](https://docs.gitlab.com/api/discussions/)
[Dockerfile (templates)](https://docs.gitlab.com/api/templates/dockerfiles/)
[DORA4 metrics](https://docs.gitlab.com/api/dora/metrics/)
[Emoji reactions](https://docs.gitlab.com/api/emoji_reactions/)
[Environments](https://docs.gitlab.com/api/environments/)
[Epics (deprecated)](https://docs.gitlab.com/api/epics/)
[Error tracking](https://docs.gitlab.com/api/error_tracking/)
[Events](https://docs.gitlab.com/api/events/)
[Experiments](https://docs.gitlab.com/api/experiments/)
[External status checks](https://docs.gitlab.com/api/status_checks/)
[Feature flags](https://docs.gitlab.com/api/feature_flags/)
[Feature flag user lists](https://docs.gitlab.com/api/feature_flag_user_lists/)
[Freeze periods](https://docs.gitlab.com/api/freeze_periods/)
[Geo nodes (deprecated)](https://docs.gitlab.com/api/geo_nodes/)
[Geo sites](https://docs.gitlab.com/api/geo_sites/)
[GitLab Duo Chat completions](https://docs.gitlab.com/api/chat/)
[GitLab Pages](https://docs.gitlab.com/api/pages/)
[GLQL](https://docs.gitlab.com/api/glql/)
[Go Proxy](https://docs.gitlab.com/api/packages/go_proxy/)
[Google Cloud integration](https://docs.gitlab.com/api/google_cloud_integration/)
[Groups](https://docs.gitlab.com/api/groups/)
[Access tokens](https://docs.gitlab.com/api/group_access_tokens/)
[Activity analytics](https://docs.gitlab.com/api/group_activity_analytics/)
[Badges](https://docs.gitlab.com/api/group_badges/)
[CI/CD variables](https://docs.gitlab.com/api/group_level_variables/)
[Enterprise users](https://docs.gitlab.com/api/group_enterprise_users/)
[Epic boards](https://docs.gitlab.com/api/group_epic_boards/)
[Import and export](https://docs.gitlab.com/api/group_import_export/)
[Integrations](https://docs.gitlab.com/api/group_integrations/)
[Issue boards](https://docs.gitlab.com/api/group_boards/)
[Iterations](https://docs.gitlab.com/api/group_iterations/)
[Labels](https://docs.gitlab.com/api/group_labels/)
[LDAP group links](https://docs.gitlab.com/api/group_ldap_links/)
[Markdown uploads](https://docs.gitlab.com/api/group_markdown_uploads/)
[Members](https://docs.gitlab.com/api/group_members/)
[Migration by direct transfer](https://docs.gitlab.com/api/bulk_imports/)
[Milestones](https://docs.gitlab.com/api/group_milestones/)
[Placeholder reassignments](https://docs.gitlab.com/api/group_placeholder_reassignments/)
[Protected branches](https://docs.gitlab.com/api/group_protected_branches/)
[Protected environments](https://docs.gitlab.com/api/group_protected_environments/)
[Push rules](https://docs.gitlab.com/api/group_push_rules/)
[Relations export](https://docs.gitlab.com/api/group_relations_export/)
[Releases](https://docs.gitlab.com/api/group_releases/)
[Repository storage moves](https://docs.gitlab.com/api/group_repository_storage_moves/)
[SAML](https://docs.gitlab.com/api/saml/)
[SCIM](https://docs.gitlab.com/api/scim/)
[Security settings](https://docs.gitlab.com/api/group_security_settings/)
[SSH certificates](https://docs.gitlab.com/api/group_ssh_certificates/)
[Webhooks](https://docs.gitlab.com/api/group_webhooks/)
[Wikis](https://docs.gitlab.com/api/group_wikis/)
[Helm](https://docs.gitlab.com/api/packages/helm/)
[Import](https://docs.gitlab.com/api/import/)
[Instance CI/CD variables](https://docs.gitlab.com/api/instance_level_ci_variables/)
[Invitations](https://docs.gitlab.com/api/invitations/)
[Issues](https://docs.gitlab.com/api/issues/)
[Issues (epic) (deprecated)](https://docs.gitlab.com/api/epic_issues/)
[Issues statistics](https://docs.gitlab.com/api/issues_statistics/)
[Jobs](https://docs.gitlab.com/api/jobs/)
[Job artifacts](https://docs.gitlab.com/api/job_artifacts/)
[Job token scopes](https://docs.gitlab.com/api/project_job_token_scopes/)
[Keys](https://docs.gitlab.com/api/keys/)
[License](https://docs.gitlab.com/api/license/)
[Licenses (templates)](https://docs.gitlab.com/api/templates/licenses/)
[Linked epics (deprecated)](https://docs.gitlab.com/api/linked_epics/)
[Links (issue)](https://docs.gitlab.com/api/issue_links/)
[Links (epic) (deprecated)](https://docs.gitlab.com/api/epic_links/)
[Lint .gitlab-ci.yml](https://docs.gitlab.com/api/lint/)
[Markdown](https://docs.gitlab.com/api/markdown/)
[Maven](https://docs.gitlab.com/api/packages/maven/)
[Maven virtual registry](https://docs.gitlab.com/api/maven_virtual_registries/)
[Member roles](https://docs.gitlab.com/api/member_roles/)
[Merge request approvals](https://docs.gitlab.com/api/merge_request_approvals/)
[Merge request approval settings](https://docs.gitlab.com/api/merge_request_approval_settings/)
[Merge request context commits](https://docs.gitlab.com/api/merge_request_context_commits/)
[Merge requests](https://docs.gitlab.com/api/merge_requests/)
[Merge trains](https://docs.gitlab.com/api/merge_trains/)
[Metadata](https://docs.gitlab.com/api/metadata/)
[Model registry](https://docs.gitlab.com/api/model_registry/)
[Namespaces](https://docs.gitlab.com/api/namespaces/)
[Notes (comments)](https://docs.gitlab.com/api/notes/)
[Notification settings](https://docs.gitlab.com/api/notification_settings/)
[npm](https://docs.gitlab.com/api/packages/npm/)
[NuGet](https://docs.gitlab.com/api/packages/nuget/)
[Organizations](https://docs.gitlab.com/api/organizations/)
[Packages](https://docs.gitlab.com/api/packages/)
[Pages domains](https://docs.gitlab.com/api/pages_domains/)
[Personal access tokens](https://docs.gitlab.com/api/personal_access_tokens/)
[Pipeline schedules](https://docs.gitlab.com/api/pipeline_schedules/)
[Pipeline trigger tokens](https://docs.gitlab.com/api/pipeline_triggers/)
[Pipelines](https://docs.gitlab.com/api/pipelines/)
[Plan limits](https://docs.gitlab.com/api/plan_limits/)
[Product analytics](https://docs.gitlab.com/api/product_analytics/)
[Projects](https://docs.gitlab.com/api/projects/)
[PyPI](https://docs.gitlab.com/api/packages/pypi/)
[Repositories](https://docs.gitlab.com/api/repositories/)
[Repository files](https://docs.gitlab.com/api/repository_files/)
[Repository submodules](https://docs.gitlab.com/api/repository_submodules/)
[Resource group](https://docs.gitlab.com/api/resource_groups/)
[Resource iteration events](https://docs.gitlab.com/api/resource_iteration_events/)
[Resource label events](https://docs.gitlab.com/api/resource_label_events/)
[Resource milestone events](https://docs.gitlab.com/api/resource_milestone_events/)
[Resource state events](https://docs.gitlab.com/api/resource_state_events/)
[Resource weight events](https://docs.gitlab.com/api/resource_weight_events/)
[Ruby gems](https://docs.gitlab.com/api/packages/rubygems/)
[Runners](https://docs.gitlab.com/api/runners/)
[Runner controllers](https://docs.gitlab.com/api/runner_controllers/)
[Runner controller tokens](https://docs.gitlab.com/api/runner_controller_tokens/)
[Search](https://docs.gitlab.com/api/search/)
[Search migrations](https://docs.gitlab.com/api/search_admin/)
[Secure files](https://docs.gitlab.com/api/secure_files/)
[Service accounts](https://docs.gitlab.com/api/service_accounts/)
[Service Ping](https://docs.gitlab.com/api/usage_data/)
[Sidekiq metrics](https://docs.gitlab.com/api/sidekiq_metrics/)
[Sidekiq queues](https://docs.gitlab.com/api/admin_sidekiq_queues/)
[Snippet repository storage moves](https://docs.gitlab.com/api/snippet_repository_storage_moves/)
[Snippets](https://docs.gitlab.com/api/snippets/)
[Suggestions](https://docs.gitlab.com/api/suggestions/)
[System hooks](https://docs.gitlab.com/api/system_hooks/)
[Tags](https://docs.gitlab.com/api/tags/)
[Terraform registry](https://docs.gitlab.com/api/packages/terraform-modules/)
[To-Do List](https://docs.gitlab.com/api/todos/)
[Token information](https://docs.gitlab.com/api/admin/token/)
[Topics](https://docs.gitlab.com/api/topics/)
[Users](https://docs.gitlab.com/api/users/)
[Version](https://docs.gitlab.com/api/version/)
[Virtual registries cleanup policies](https://docs.gitlab.com/api/virtual_registries_cleanup_policies/)
[Vulnerabilities](https://docs.gitlab.com/api/vulnerabilities/)
[Vulnerability archive export](https://docs.gitlab.com/api/vulnerability_archive_exports/)
[Vulnerability export](https://docs.gitlab.com/api/vulnerability_exports/)
[Vulnerability findings](https://docs.gitlab.com/api/vulnerability_findings/)
[Web commits](https://docs.gitlab.com/api/web_commits/)
[Authentication](https://docs.gitlab.com/api/rest/authentication/)
[Third-party clients](https://docs.gitlab.com/api/rest/third_party_clients/)
[Deprecations and removals](https://docs.gitlab.com/api/rest/deprecations/)
[OpenAPI](https://docs.gitlab.com/api/openapi/openapi_interactive/)
[Automate storage management](https://docs.gitlab.com/user/storage_management_automation/)
[Troubleshooting](https://docs.gitlab.com/api/rest/troubleshooting/)
[GraphQL API](https://docs.gitlab.com/api/graphql/)
[OAuth 2.0 identity provider API](https://docs.gitlab.com/api/oauth2/)
[GitLab Duo CLI (duo)](https://docs.gitlab.com/user/gitlab_duo_cli/)
[GitLab CLI (glab)](https://docs.gitlab.com/cli/)
[Editor and IDE extensions](https://docs.gitlab.com/editor_extensions/)
/
  1. [GitLab Docs](https://docs.gitlab.com/)
  2. [Extend](https://docs.gitlab.com/api/)
  3. [REST API](https://docs.gitlab.com/api/rest/)
  4. [Resources](https://docs.gitlab.com/api/api_resources/)
  5. [Groups](https://docs.gitlab.com/api/groups/)


* * *
# Groups API
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


Use this API to view and manage GitLab groups. For more information, see [groups](https://docs.gitlab.com/user/group/).
Endpoint responses might vary based on the [permissions](https://docs.gitlab.com/user/permissions/) of the authenticated user in the group.
## Retrieve a group[](https://docs.gitlab.com/api/groups/#retrieve-a-group "Permalink")
Retrieve details of a group. This endpoint can be accessed without authentication if the group is publicly accessible. In case the user that requests is an administrator if the group is publicly accessible. With authentication, it returns the `runners_token` and `enabled_git_access_protocol` for the group too, if the user is an administrator or has the Owner role.
```
GET /groups/:id
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`with_custom_attributes` | boolean | no | Include [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in response (administrators only).
`with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). (Deprecated, [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects in a group, use the [list a group’s projects endpoint](https://docs.gitlab.com/api/groups/#list-projects).)
The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use either the [list a group’s projects](https://docs.gitlab.com/api/groups/#list-projects) or the [list a group’s shared projects](https://docs.gitlab.com/api/groups/#list-shared-projects) endpoint.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4"
```

This endpoint returns a maximum of 100 projects and shared projects. To get the details of all projects within a group, use the [list a group’s projects endpoint](https://docs.gitlab.com/api/groups/#list-projects) instead.
Example response:
json
```
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "runners_token": "ba324ca7b1c77fc20bb9",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "shared_with_groups": [
    {
      "group_id": 28,
      "group_name": "H5bp",
      "group_full_path": "h5bp",
      "group_access_level": 20,
      "expires_at": null
    }
  ],
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 7,
      "description": "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "public",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/typeahead-js.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/typeahead-js.git",
      "web_url": "https://gitlab.example.com/twitter/typeahead-js",
      "name": "Typeahead.Js",
      "name_with_namespace": "Twitter / Typeahead.Js",
      "path": "typeahead-js",
      "path_with_namespace": "twitter/typeahead-js",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:25.578Z",
      "last_activity_at": "2016-06-17T07:47:25.881Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    },
    {
      "id": 6,
      "description": "Aspernatur omnis repudiandae qui voluptatibus eaque.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com:twitter/flight.git",
      "http_url_to_repo": "https://gitlab.example.com/twitter/flight.git",
      "web_url": "https://gitlab.example.com/twitter/flight",
      "name": "Flight",
      "name_with_namespace": "Twitter / Flight",
      "path": "flight",
      "path_with_namespace": "twitter/flight",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:24.661Z",
      "last_activity_at": "2016-06-17T07:47:24.838Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 4,
        "name": "Twitter",
        "path": "twitter",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 8,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "shared_projects": [ // Deprecated and will be removed in API v5
    {
      "id": 8,
      "description": "Velit eveniet provident fugiat saepe eligendi autem.",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "archived": false,
      "visibility": "private",
      "ssh_url_to_repo": "git@gitlab.example.com:h5bp/html5-boilerplate.git",
      "http_url_to_repo": "https://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "https://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "H5bp / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": false,
      "container_registry_enabled": true,
      "created_at": "2016-06-17T07:47:27.089Z",
      "last_activity_at": "2016-06-17T07:47:27.310Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "H5bp",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 0,
      "forks_count": 0,
      "open_issues_count": 4,
      "public_jobs": true,
      "shared_with_groups": [
        {
          "group_id": 4,
          "group_name": "Twitter",
          "group_full_path": "twitter",
          "group_access_level": 30,
          "expires_at": null
        },
        {
          "group_id": 3,
          "group_name": "Gitlab Org",
          "group_full_path": "gitlab-org",
          "group_access_level": 10,
          "expires_at": "2018-08-14"
        }
      ]
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false
}
```

The `prevent_sharing_groups_outside_hierarchy` attribute is present only on top-level groups.
Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the attributes:
  * `shared_runners_minutes_limit`
  * `extra_shared_runners_minutes_limit`
  * `marked_for_deletion_on`
  * `membership_lock`
  * `wiki_access_level`
  * `duo_features_enabled`
  * `lock_duo_features_enabled`
  * `duo_availability`
  * `experiment_features_enabled`


Additional response attributes:
json
```
{
  "id": 4,
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "marked_for_deletion_on": "2020-04-03",
  "membership_lock": false,
  "wiki_access_level": "disabled",
  "duo_features_enabled": true,
  "lock_duo_features_enabled": false,
  "duo_availability": "default_on",
  "experiment_features_enabled": false,
  ...
}
```

When adding the parameter `with_projects=false`, projects aren’t returned.
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4?with_projects=false"
```

Example response:
json
```
{
  "id": 4,
  "name": "Twitter",
  "path": "twitter",
  "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",
  "visibility": "public",
  "avatar_url": null,
  "web_url": "https://gitlab.example.com/groups/twitter",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Twitter",
  "full_path": "twitter",
  "file_template_project_id": 1,
  "parent_id": null
}
```

## List groups[](https://docs.gitlab.com/api/groups/#list-groups "Permalink")
### List all groups[](https://docs.gitlab.com/api/groups/#list-all-groups "Permalink")
List 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](https://docs.gitlab.com/api/rest/#pagination).
When accessed without authentication, this endpoint also supports [keyset pagination](https://docs.gitlab.com/api/rest/#keyset-based-pagination):
  * When requesting consecutive pages of results, you should use keyset pagination.
  * Beyond a specific offset limit (specified by [max offset allowed by the REST API for offset-based pagination](https://docs.gitlab.com/administration/instance_limits/#max-offset-allowed-by-the-rest-api-for-offset-based-pagination)), offset pagination is unavailable.


Parameters:
Attribute | Type | Required | Description
---|---|---|---
`skip_groups` | array of integers | no | Skip the group IDs passed.
`all_available` | boolean | no | When `true`, returns all accessible groups. When `false`, returns only groups where the user is a member. Defaults to `false` for users, `true` for administrators. Unauthenticated requests always return all public groups. The `owned` and `min_access_level` attributes take 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`. Default is `name`.
`sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc`.
`statistics` | boolean | no | Include group statistics (administrators only).
For top-level groups, the response returns the full `root_storage_statistics` data displayed in the UI. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/469254) in GitLab 17.4.
`visibility` | string | no | Limit to groups with `public`, `internal`, or `private` visibility.
`with_custom_attributes` | boolean | no | Include [custom attributes](https://docs.gitlab.com/api/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 the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`top_level_only` | boolean | no | Limit to top-level groups, excluding all subgroups.
`repository_storage` | string | no | Filter by repository storage used by the group (administrators only). [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/419643) in GitLab 16.3. Premium and Ultimate only.
`marked_for_deletion_on` | date | no | Filter by date when group was marked for deletion. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/429315) in GitLab 17.1. Premium and Ultimate only.
`active` | boolean | no | Limit by groups that are not archived and not marked for deletion.
`archived` | boolean | no | Limit by groups that are archived. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/519587) in GitLab 18.2. This parameter is an experiment.
```
GET /groups
```

json
```
[
  {
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": null,
    "created_at": "2020-01-15T12:36:29.590Z",
    "ip_restriction_ranges": null
  }
]
```

When adding the parameter `statistics=true` and the authenticated user is an administrator, additional group statistics are returned. For top-level groups, `root_storage_statistics` are added as well.
```
GET /groups?statistics=true
```

When the parameter `statistics=true` is used and the authenticated user is an administrator, the response includes information about container registry storage size:
  * `container_registry_size`: Total storage size in bytes used by all container repositories in the group and its subgroups. Calculated as the sum of all repository sizes within the group’s projects and subgroups. Available only when the container registry metadata database is enabled.
  * `container_registry_size_is_estimated`: Indicates whether the size is an exact calculation based on actual data from all repositories (`false`) or estimated due to performance constraints (`true`).


For GitLab Self-Managed instances, the [container registry metadata database](https://docs.gitlab.com/administration/packages/container_registry_metadata_database/) must be enabled to include the container registry size attributes.
json
```
[
  {
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://localhost:3000/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "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
    },
    "root_storage_statistics": {
      "build_artifacts_size": 0,
      "container_registry_size": 0,
      "container_registry_size_is_estimated": false,
      "dependency_proxy_size": 0,
      "lfs_objects_size": 0,
      "packages_size": 0,
      "pipeline_artifacts_size": 0,
      "repository_size": 0,
      "snippets_size": 0,
      "storage_size": 0,
      "uploads_size": 0,
      "wiki_size": 0
  },
    "wiki_access_level": "private",
    "duo_features_enabled": true,
    "lock_duo_features_enabled": false,
    "duo_availability": "default_on",
    "experiment_features_enabled": false,
  }
]
```

Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level`, `duo_features_enabled`, `lock_duo_features_enabled`, `duo_availability`, and `experiment_features_enabled` attributes.
You can search for groups by name or path, see below.
You can filter by [custom attributes](https://docs.gitlab.com/api/custom_attributes/) with:
```
GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value
```

#### Group pagination[](https://docs.gitlab.com/api/groups/#group-pagination "Permalink")
By default, only 20 groups are displayed at a time because the API results are paginated.
To get more (up to 100), pass the following as an argument to the API call:
```
/groups?per_page=100
```

And to switch pages add:
```
/groups?per_page=100&page=2
```

### Search for a group[](https://docs.gitlab.com/api/groups/#search-for-a-group "Permalink")
Search for groups that match a string in their name or path.
```
GET /groups?search=foobar
```

json
```
[
  {
    "id": 1,
    "name": "Foobar Group",
    "path": "foo-bar",
    "description": "An interesting group"
  }
]
```

## List group details[](https://docs.gitlab.com/api/groups/#list-group-details "Permalink")
### List projects[](https://docs.gitlab.com/api/groups/#list-projects "Permalink")
List projects in a group. When accessed without authentication, only public projects are returned.
By default, this request returns 20 results at a time because the API results [are paginated](https://docs.gitlab.com/api/rest/#pagination).
```
GET /groups/:id/projects
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`active` | boolean | no | Limit by project status. When `true`, returns active projects. When `false`, returns projects that are archived or marked for deletion. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/218053) in GitLab 18.8.
`archived` | boolean | no | Limit by archived status.
`visibility` | string | no | Limit by visibility `public`, `internal`, or `private`.
`order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `similarity` 1, `star_count` or `last_activity_at` fields. Default is `created_at`.
`sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc`.
`search` | string | no | Return list of authorized projects matching the search criteria.
`simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned.
`owned` | boolean | no | Limit by projects owned by the current user.
`starred` | boolean | no | Limit by projects starred by the current user.
`topic` | string | no | Return projects matching the topic.
`with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false`.
`with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false`.
`with_shared` | boolean | no | Include projects shared to this group. Default is `true`.
`include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false`.
`min_access_level` | integer | no | Limit to projects where current user has at least the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`with_custom_attributes` | boolean | no | Include [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in response (administrators only).
`with_security_reports` | boolean | no | Return only projects that have security reports artifacts present in any of their builds. This means “projects with security reports enabled”. Default is `false`. Ultimate only.
**Footnotes** :
  1. Orders the results by a similarity score calculated from the `search` URL parameter. When you use `order_by=similarity`, the `sort` parameter is ignored. When the `search` parameter is not provided, the API returns the projects ordered by `name`.


Example response:
json
```
[
  {
    "id": 9,
    "description": "foo",
    "default_branch": "main",
    "tag_list": [], //deprecated, use `topics` instead
    "topics": [],
    "archived": false,
    "visibility": "internal",
    "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
    "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
    "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
    "name": "Html5 Boilerplate",
    "name_with_namespace": "Experimental / Html5 Boilerplate",
    "path": "html5-boilerplate",
    "path_with_namespace": "h5bp/html5-boilerplate",
    "issues_enabled": true,
    "merge_requests_enabled": true,
    "wiki_enabled": true,
    "jobs_enabled": true,
    "snippets_enabled": true,
    "created_at": "2016-04-05T21:40:50.169Z",
    "last_activity_at": "2016-04-06T16:52:08.432Z",
    "shared_runners_enabled": true,
    "creator_id": 1,
    "namespace": {
      "id": 5,
      "name": "Experimental",
      "path": "h5bp",
      "kind": "group"
    },
    "avatar_url": null,
    "star_count": 1,
    "forks_count": 0,
    "open_issues_count": 3,
    "public_jobs": true,
    "shared_with_groups": [],
    "request_access_enabled": false
  }
]
```

To distinguish between a project in the group and a project shared to the group, the `namespace` attribute can be used. When a project has been shared to the group, its `namespace` differs from the group the request is being made for.
### List shared projects[](https://docs.gitlab.com/api/groups/#list-shared-projects "Permalink")
List projects shared to a group. When accessed without authentication, only public shared projects are returned.
By default, this request returns 20 results at a time because the API results [are paginated](https://docs.gitlab.com/api/rest/#pagination).
```
GET /groups/:id/projects/shared
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`archived` | boolean | no | Limit by archived status.
`visibility` | string | no | Limit by visibility `public`, `internal`, or `private`.
`order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, `star_count` or `last_activity_at` fields. Default is `created_at`.
`sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc`.
`search` | string | no | Return list of authorized projects matching the search criteria.
`simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication where only simple fields are returned.
`starred` | boolean | no | Limit by projects starred by the current user.
`with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false`.
`with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false`.
`min_access_level` | integer | no | Limit to projects where current user has at least the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`with_custom_attributes` | boolean | no | Include [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in response (administrators only).
Example response:
json
```
[
   {
      "id":8,
      "description":"Shared project for Html5 Boilerplate",
      "name":"Html5 Boilerplate",
      "name_with_namespace":"H5bp / Html5 Boilerplate",
      "path":"html5-boilerplate",
      "path_with_namespace":"h5bp/html5-boilerplate",
      "created_at":"2020-04-27T06:13:22.642Z",
      "default_branch":"main",
      "tag_list":[], //deprecated, use `topics` instead
      "topics":[],
      "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",
      "http_url_to_repo":"https://gitlab.com/h5bp/html5-boilerplate.git",
      "web_url":"https://gitlab.com/h5bp/html5-boilerplate",
      "readme_url":"https://gitlab.com/h5bp/html5-boilerplate/-/blob/main/README.md",
      "avatar_url":null,
      "star_count":0,
      "forks_count":4,
      "last_activity_at":"2020-04-27T06:13:22.642Z",
      "namespace":{
         "id":28,
         "name":"H5bp",
         "path":"h5bp",
         "kind":"group",
         "full_path":"h5bp",
         "parent_id":null,
         "avatar_url":null,
         "web_url":"https://gitlab.com/groups/h5bp"
      },
      "_links":{
         "self":"https://gitlab.com/api/v4/projects/8",
         "issues":"https://gitlab.com/api/v4/projects/8/issues",
         "merge_requests":"https://gitlab.com/api/v4/projects/8/merge_requests",
         "repo_branches":"https://gitlab.com/api/v4/projects/8/repository/branches",
         "labels":"https://gitlab.com/api/v4/projects/8/labels",
         "events":"https://gitlab.com/api/v4/projects/8/events",
         "members":"https://gitlab.com/api/v4/projects/8/members"
      },
      "empty_repo":false,
      "archived":false,
      "visibility":"public",
      "resolve_outdated_diff_discussions":false,
      "container_registry_enabled":true,
      "container_expiration_policy":{
         "cadence":"7d",
         "enabled":true,
         "keep_n":null,
         "older_than":null,
         "name_regex":null,
         "name_regex_keep":null,
         "next_run_at":"2020-05-04T06:13:22.654Z"
      },
      "issues_enabled":true,
      "merge_requests_enabled":true,
      "wiki_enabled":true,
      "jobs_enabled":true,
      "snippets_enabled":true,
      "can_create_merge_request_in":true,
      "issues_access_level":"enabled",
      "repository_access_level":"enabled",
      "merge_requests_access_level":"enabled",
      "forking_access_level":"enabled",
      "wiki_access_level":"enabled",
      "builds_access_level":"enabled",
      "snippets_access_level":"enabled",
      "pages_access_level":"enabled",
      "security_and_compliance_access_level":"enabled",
      "emails_disabled":null,
      "emails_enabled": null,
      "shared_runners_enabled":true,
      "lfs_enabled":true,
      "creator_id":1,
      "import_status":"failed",
      "open_issues_count":10,
      "ci_default_git_depth":50,
      "ci_forward_deployment_enabled":true,
      "ci_forward_deployment_rollback_allowed": true,
      "ci_allow_fork_pipelines_to_run_in_parent_project":true,
      "public_jobs":true,
      "build_timeout":3600,
      "auto_cancel_pending_pipelines":"enabled",
      "ci_config_path":null,
      "shared_with_groups":[
         {
            "group_id":24,
            "group_name":"Commit451",
            "group_full_path":"Commit451",
            "group_access_level":30,
            "expires_at":null
         }
      ],
      "only_allow_merge_if_pipeline_succeeds":false,
      "request_access_enabled":true,
      "only_allow_merge_if_all_discussions_are_resolved":false,
      "remove_source_branch_after_merge":true,
      "printing_merge_request_link_enabled":true,
      "merge_method":"merge",
      "suggestion_commit_message":null,
      "auto_devops_enabled":true,
      "auto_devops_deploy_strategy":"continuous",
      "autoclose_referenced_issues":true,
      "repository_storage":"default"
   }
]
```

### List all SAML users[](https://docs.gitlab.com/api/groups/#list-all-saml-users "Permalink")
  * Tier: Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/193748) in GitLab 18.1.


Lists all SAML users for a given top-level group.
Use the `page` and `per_page` [pagination parameters](https://docs.gitlab.com/api/rest/#offset-based-pagination) to filter the results.
```
GET /groups/:id/saml_users
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a top-level group.
`username` | string | no | Return a user with a given username.
`search` | string | no | Return users with a matching name, email, or username. Use partial values to increase results.
`active` | boolean | no | Return only active users.
`blocked` | boolean | no | Return only blocked users.
`created_after` | datetime | no | Return users created after the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
`created_before` | datetime | no | Return users created before the specified time. Format: ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`).
Example request:
shell
```
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/saml_users"
```

Example response:
json
```
[
  {
    "id": 66,
    "username": "user22",
    "name": "Sidney Jones22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [
      {
        "provider": "group_saml",
        "extern_uid": "2435223452345",
        "saml_provider_id": 1
      }
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null,
    "scim_identities": [
      {
        "extern_uid": "2435223452345",
        "group_id": 1,
        "active": true
      }
    ]
  },
  ...
]
```

### List provisioned users[](https://docs.gitlab.com/api/groups/#list-provisioned-users "Permalink")
  * Tier: Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


List users provisioned by a group. Does not include subgroups.
Requires the Maintainer or Owner role on the group.
```
GET /groups/:id/provisioned_users
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`username` | string | no | Return single user with a specific username.
`search` | string | no | Search users by name, email, username.
`active` | boolean | no | Return only active users.
`blocked` | boolean | no | Return only blocked users.
`created_after` | datetime | no | Return users created after the specified time.
`created_before` | datetime | no | Return users created before the specified time.
Example response:
json
```
[
  {
    "id": 66,
    "username": "user22",
    "name": "John Doe22",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/xxx?s=80&d=identicon",
    "web_url": "http://my.gitlab.com/user22",
    "created_at": "2021-09-10T12:48:22.381Z",
    "bio": "",
    "location": null,
    "public_email": "",
    "linkedin": "",
    "twitter": "",
    "website_url": "",
    "organization": null,
    "job_title": "",
    "pronouns": null,
    "bot": false,
    "work_information": null,
    "followers": 0,
    "following": 0,
    "local_time": null,
    "last_sign_in_at": null,
    "confirmed_at": "2021-09-10T12:48:22.330Z",
    "last_activity_on": null,
    "email": "user22@example.org",
    "theme_id": 1,
    "color_scheme_id": 1,
    "projects_limit": 100000,
    "current_sign_in_at": null,
    "identities": [ ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": false,
    "external": false,
    "private_profile": false,
    "commit_email": "user22@example.org",
    "shared_runners_minutes_limit": null,
    "extra_shared_runners_minutes_limit": null
  },
  ...
]
```

### List subgroups[](https://docs.gitlab.com/api/groups/#list-subgroups "Permalink")
List visible direct subgroups in a group.
By default, this request returns 20 results at a time because the API results [are paginated](https://docs.gitlab.com/api/rest/#pagination).
If you request this list as:
  * An unauthenticated user, the response returns only public groups.
  * An authenticated user, the response returns only the groups you’re a member of and does not include public groups.


Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) 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](https://docs.gitlab.com/api/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 the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`all_available` | boolean | no | When `true`, returns all accessible groups. When `false`, returns only groups where the user is a member. Defaults to `false` for users, `true` for administrators. Unauthenticated requests always return all public groups. The `owned` and `min_access_level` attributes take precedence.
`active` | boolean | no | Limit by groups that are not archived and not marked for deletion.
```
GET /groups/:id/subgroups
```

json
```
[
  {
    "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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",
    "web_url": "http://gitlab.example.com/groups/foo-bar",
    "request_access_enabled": false,
    "repository_storage": "default",
    "full_name": "Foobar Group",
    "full_path": "foo-bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]
```

Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level`, `duo_features_enabled`, `lock_duo_features_enabled`, `duo_availability`, and `experiment_features_enabled` attributes.
### List descendant groups[](https://docs.gitlab.com/api/groups/#list-descendant-groups "Permalink")
List visible descendant groups of a 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](https://docs.gitlab.com/api/rest/#pagination).
Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group of the immediate parent group.
`skip_groups` | array of integers | no | Skip the group IDs passed.
`all_available` | boolean | no | When `true`, returns all accessible groups. When `false`, returns only groups where the user is a member. Defaults to `false` for users, `true` for administrators. Unauthenticated requests always return all public groups. The `owned` and `min_access_level` attributes take precedence.
`search` | string | no | Return the list of authorized groups matching the search criteria. Only descendant group 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](https://docs.gitlab.com/api/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 the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`active` | boolean | no | Limit by groups that are not archived and not marked for deletion.
```
GET /groups/:id/descendant_groups
```

json
```
[
  {
    "id": 2,
    "name": "Bar Group",
    "path": "bar",
    "description": "A subgroup of Foo 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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/bar.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar",
    "request_access_enabled": false,
    "full_name": "Bar Group",
    "full_path": "foo/bar",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  },
  {
    "id": 3,
    "name": "Baz Group",
    "path": "baz",
    "description": "A subgroup of Bar 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,
    "emails_enabled": null,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
          {
              "access_level": 40
          }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
          {
              "access_level": 40
          }
      ]
    },
    "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/baz.jpg",
    "web_url": "http://gitlab.example.com/groups/foo/bar/baz",
    "request_access_enabled": false,
    "full_name": "Baz Group",
    "full_path": "foo/bar/baz",
    "file_template_project_id": 1,
    "parent_id": 123,
    "created_at": "2020-01-15T12:36:29.590Z"
  }
]
```

Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level`, `duo_features_enabled`, `lock_duo_features_enabled`, `duo_availability`, and `experiment_features_enabled` attributes.
### List shared groups[](https://docs.gitlab.com/api/groups/#list-shared-groups "Permalink")
List groups where the given group has been invited. When accessed without authentication, only public shared groups are returned.
By default, this request returns 20 results at a time because the API results [are paginated](https://docs.gitlab.com/api/rest/#pagination).
Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`skip_groups` | array of integers | no | Skip the specified group IDs.
`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`. Default is `name`.
`sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc`.
`visibility` | string | no | Limit to groups with `public`, `internal`, or `private` visibility.
`min_access_level` | integer | no | Limit to groups where current user has at least the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`with_custom_attributes` | boolean | no | Include [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in response (administrators only).
```
GET /groups/:id/groups/shared
```

Example response:
json
```
[
  {
    "id": 101,
    "web_url": "http://gitlab.example.com/groups/some_path",
    "name": "group1",
    "path": "some_path",
    "description": "",
    "visibility": "public",
    "share_with_group_lock": "false",
    "require_two_factor_authentication": "false",
    "two_factor_grace_period": 48,
    "project_creation_level": "maintainer",
    "auto_devops_enabled": "nil",
    "subgroup_creation_level": "maintainer",
    "emails_disabled": "false",
    "emails_enabled": "true",
    "mentions_disabled": "nil",
    "lfs_enabled": "true",
    "math_rendering_limits_enabled": "true",
    "lock_math_rendering_limits_enabled": "false",
    "default_branch": "nil",
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
        "allowed_to_push": [
          {
              "access_level": 30
          }
        ],
        "allow_force_push": "true",
        "allowed_to_merge": [
          {
              "access_level": 30
          }
        ],
        "developer_can_initial_push": "false",
        "code_owner_approval_required": "false"
    },
    "avatar_url": "http://gitlab.example.com/uploads/-/system/group/avatar/101/banana_sample.gif",
    "request_access_enabled": "true",
    "full_name": "group1",
    "full_path": "some_path",
    "created_at": "2024-06-06T09:39:30.056Z",
    "parent_id": "nil",
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": "nil",
    "ldap_access": "nil",
    "wiki_access_level": "enabled"
  }
]
```

### List invited groups[](https://docs.gitlab.com/api/groups/#list-invited-groups "Permalink")
List invited groups in a group. When accessed without authentication, only public invited groups are returned. This endpoint is rate-limited to 60 requests per minute per user (for authenticated users) or IP (for unauthenticated users).
By default, this request returns 20 results at a time because the API results [are paginated](https://docs.gitlab.com/api/rest/#pagination).
Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`search` | string | no | Return the list of authorized groups matching the search criteria.
`min_access_level` | integer | no | Limit to groups where current user has at least the specified access level. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`relation` | array of strings | no | Filter the groups by relation (direct or inherited).
`with_custom_attributes` | boolean | no | Include [custom attributes](https://docs.gitlab.com/api/custom_attributes/) in response (administrators only).
```
GET /groups/:id/invited_groups
```

Example response:
json
```
[
  {
    "id": 33,
    "web_url": "http://gitlab.example.com/groups/flightjs",
    "name": "Flightjs",
    "path": "flightjs",
    "description": "Illo dolorum tempore eligendi minima ducimus provident.",
    "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": "maintainer",
    "emails_disabled": false,
    "emails_enabled": true,
    "mentions_disabled": null,
    "lfs_enabled": true,
    "math_rendering_limits_enabled": true,
    "lock_math_rendering_limits_enabled": false,
    "default_branch": null,
    "default_branch_protection": 2,
    "default_branch_protection_defaults": {
      "allowed_to_push": [
        {
          "access_level": 40
        }
      ],
      "allow_force_push": false,
      "allowed_to_merge": [
        {
          "access_level": 40
        }
      ],
      "developer_can_initial_push": false
    },
    "avatar_url": null,
    "request_access_enabled": true,
    "full_name": "Flightjs",
    "full_path": "flightjs",
    "created_at": "2024-07-09T10:31:08.307Z",
    "parent_id": null,
    "organization_id": 1,
    "shared_runners_setting": "enabled",
    "ldap_cn": null,
    "ldap_access": null,
    "wiki_access_level": "enabled"
  }
]
```

### List audit events[](https://docs.gitlab.com/api/groups/#list-audit-events "Permalink")
  * Tier: Premium, Ultimate
  * Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated


Group audit events can be accessed via the [Group audit events API](https://docs.gitlab.com/api/audit_events/#group-audit-events)
## Manage groups[](https://docs.gitlab.com/api/groups/#manage-groups "Permalink")
### Create a group[](https://docs.gitlab.com/api/groups/#create-a-group "Permalink")
On GitLab SaaS, you must use the GitLab UI to create groups without a parent group. You cannot use the API to do this.
Creates a new project group. Available only for users who can create groups.
```
POST /groups
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`name` | string | yes | The name of the group.
`path` | string | yes | The path of the group.
`auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group.
`avatar` | mixed | no | Image file for avatar of the group.
`default_branch` | string | no | The [default branch](https://docs.gitlab.com/user/project/repository/branches/default/) name for group’s projects. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442298) in GitLab 16.11.
`default_branch_protection` | integer | no |  [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/408314) in GitLab 17.0. Use `default_branch_protection_defaults` instead.
`default_branch_protection_defaults` | hash | no | Introduced in GitLab 17.0. For available options, see [Options for `default_branch_protection_defaults`](https://docs.gitlab.com/api/groups/#options-for-default_branch_protection_defaults).
`description` | string | no | The group’s description.
`enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `all` to allow both protocols. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436618) in GitLab 16.9.
`emails_disabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127899) in GitLab 16.5.) Disable email notifications. Use `emails_enabled` instead.
`emails_enabled` | boolean | no | Enable email notifications.
`lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group.
`mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned.
`organization_id` | integer | no | The organization ID for the group.
`parent_id` | integer | no | The parent group ID for creating nested group.
`project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `administrator` (users with Admin Mode enabled), `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role).
`request_access_enabled` | boolean | no | Allow users to request member access.
`require_two_factor_authentication` | boolean | no | Require all users in this group to set up two-factor authentication.
`share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group.
`subgroup_creation_level` | string | no | Allowed to [create subgroups](https://docs.gitlab.com/user/group/subgroups/#create-a-subgroup). Can be `owner` (users with the Owner role), or `maintainer` (users with the Maintainer role).
`two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours).
`visibility` | string | no | The group’s visibility. Can be `private`, `internal`, or `public`.
`membership_lock` | boolean | no | Users cannot be added to projects in this group. Premium and Ultimate only.
`extra_shared_runners_minutes_limit` | integer | no | Can be set by administrators only. Additional compute minutes for this group. GitLab Self-Managed, Premium and Ultimate only.
`shared_runners_minutes_limit` | integer | no | Can be set by administrators only. Maximum number of monthly compute minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. GitLab Self-Managed, Premium and Ultimate only.
`wiki_access_level` | string | no | The wiki access level. Can be `disabled`, `private`, or `enabled`. Premium and Ultimate only.
`duo_availability` | string | no | GitLab Duo availability setting. Valid values are: `default_on`, `default_off`, `never_on`. Note: In the UI, `never_on` is displayed as “Always Off”.
`experiment_features_enabled` | boolean | no | Enable experiment features for this group.
#### Options for `default_branch_protection`[](https://docs.gitlab.com/api/groups/#options-for-default_branch_protection "Permalink")
The `default_branch_protection` attribute determines whether users with the Developer or Maintainer role can push to the applicable [default branch](https://docs.gitlab.com/user/project/repository/branches/default/), as described in the following table:
Value | Description
---|---
`0` | No protection. Users with the Developer or Maintainer role can:
- Push new commits.
- Force push changes.
- Delete the branch.
`1` | Partial protection. Users with the Developer or Maintainer role can:
- Push new commits.
`2` | Full protection. Only users with the Maintainer role can:
- Push new commits.
`3` | Protected against pushes. Users with the Maintainer role can:
- Push new commits.
- Force push changes.
- Accept merge requests.
Users with the Developer role can:
- Accept merge requests.
`4` | Full protection after initial push. User with the Developer role can:
- Push commit to empty repository.
Users with the Maintainer role can:
- Push new commits.
- Accept merge requests.
#### Options for `default_branch_protection_defaults`[](https://docs.gitlab.com/api/groups/#options-for-default_branch_protection_defaults "Permalink")
History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408314) in GitLab 17.0.


The `default_branch_protection_defaults` attribute describes the default branch protection defaults. All parameters are optional.
Key | Type | Description
---|---|---
`allowed_to_push` | array | An array of access levels allowed to push. Supports Developer (30) or Maintainer (40).
`allow_force_push` | boolean | Allow force push for all users with push access.
`allowed_to_merge` | array | An array of access levels allowed to merge. Supports Developer (30) or Maintainer (40).
`developer_can_initial_push` | boolean | Allow developers to initial push.
`code_owner_approval_required` | boolean | Require Code Owner approval.
### Create a subgroup[](https://docs.gitlab.com/api/groups/#create-a-subgroup "Permalink")
This is similar to creating a [New group](https://docs.gitlab.com/api/groups/#create-a-group). You need the `parent_id` from the [List groups](https://docs.gitlab.com/api/groups/#list-groups) call. You can then enter the desired:
  * `subgroup_path`
  * `subgroup_name`


shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> }' \
  --url "https://gitlab.example.com/api/v4/groups/"
```

### Schedule a group for deletion[](https://docs.gitlab.com/api/groups/#schedule-a-group-for-deletion "Permalink")
History
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/389557) in GitLab 16.0. Premium and Ultimate only.
  * [Moved](https://gitlab.com/groups/gitlab-org/-/epics/17208) from GitLab Premium to GitLab Free in GitLab 18.0.


Schedules a group for deletion. Groups are deleted at the end of the retention period:
  * On GitLab.com, groups are retained for 30 days.
  * On GitLab Self-Managed, the retention period is controlled by the [instance settings](https://docs.gitlab.com/administration/settings/visibility_and_access_controls/#deletion-protection).


This endpoint can also immediately delete a subgroup that was previously scheduled for deletion.
Prerequisites:
  * You must be an administrator or have the Owner role for the group.


```
DELETE /groups/:id
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`full_path` | string | Conditional | The full path to the subgroup. Used to confirm deletion of the subgroup. If `permanently_remove` is `true`, this attribute is required. To find the subgroup path, see the [group details](https://docs.gitlab.com/api/groups/#retrieve-a-group).
`permanently_remove` | boolean/string | No | If `true`, immediately deletes a subgroup that is already scheduled for deletion. Cannot delete top-level groups.
If successful, returns a [`202 Accepted`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) status code.
Example request:
shell
```
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/:id"
```

You cannot delete a GitLab.com group that is linked to a subscription. You must first [link the subscription](https://docs.gitlab.com/subscriptions/manage_subscription/#link-subscription-to-a-group) with a different group.
#### Delete a group permanently[](https://docs.gitlab.com/api/groups/#delete-a-group-permanently "Permalink")
Bypasses the configured retention period and deletes a group and its data permanently.
Prerequisites:
  * You must be an administrator or have the Owner role for the group.


```
DELETE /groups/:id
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
`full_path` | string | Yes | The full path to the subgroup. Used to confirm deletion of the subgroup. If `permanently_remove` is `true`, this attribute is required. To find the subgroup path, see the [group details](https://docs.gitlab.com/api/groups/#retrieve-a-group).
`permanently_remove` | boolean/string | Yes | If `true`, permanently deletes a subgroup that is already scheduled for deletion. Cannot delete top-level groups.
If successful, returns a [`202 Accepted`](https://docs.gitlab.com/api/rest/troubleshooting/#status-codes) status code.
To permanently delete a group scheduled for deletion, you must:
  1. Schedule the group for deletion with an API call.
  2. In a second API call, delete the group.


For example:
shell
```
# Schedule a group for deletion
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --url "https://gitlab.example.com/api/v4/groups/:id"

# Permanently delete a group scheduled for deletion
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Accept: application/json" \
  --data '{"full_path": <full_path>, "permanently_remove": "true"}' \
  --url "https://gitlab.example.com/api/v4/groups/:id"
```

#### Restore a group marked for deletion[](https://docs.gitlab.com/api/groups/#restore-a-group-marked-for-deletion "Permalink")
Restores a group that was previously marked for deletion.
```
POST /groups/:id/restore
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group.
### Archive a group[](https://docs.gitlab.com/api/groups/#archive-a-group "Permalink")
  * Status: Experiment


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481969) in GitLab 18.0 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `archive_group`. Disabled by default. This feature is an [experiment](https://docs.gitlab.com/policy/development_stages_support/).
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/526771) in GitLab 18.9. Feature flag `archive_group` removed.


Archive a group.
Prerequisites:
  * You must be an administrator or have the Owner role for the group.


This endpoint returns a `422` unprocessable entity error if the group is already archived.
```
POST /groups/:id/archive
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group owned by the authenticated user.
Example response:
json
```
{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "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": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": true,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}
```

#### Unarchive a group[](https://docs.gitlab.com/api/groups/#unarchive-a-group "Permalink")
  * Status: Experiment


History
  * [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/481969) in GitLab 18.0 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `archive_group`. Disabled by default. This feature is an [experiment](https://docs.gitlab.com/policy/development_stages_support/).
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/526771) in GitLab 18.9. Feature flag `archive_group` removed.


Unarchive a group.
Prerequisites:
  * You must be an administrator or have the Owner role for the group.


This endpoint returns a `422` unprocessable entity error if the group is not archived.
```
POST /groups/:id/unarchive
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of the group owned by the authenticated user.
Example response:
json
```
{
  "id": 96,
  "web_url": "https://gitlab.example.com/groups/test-1",
  "name": "test-1",
  "path": "test-1",
  "description": "",
  "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": "maintainer",
  "emails_disabled": false,
  "emails_enabled": true,
  "mentions_disabled": null,
  "lfs_enabled": true,
  "archived": false,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false,
  "default_branch": null,
  "default_branch_protection": 2,
  "default_branch_protection_defaults": {
    "allowed_to_push": [
      {
        "access_level": 40
      }
    ],
    "allow_force_push": false,
    "allowed_to_merge": [
      {
        "access_level": 40
      }
    ],
    "developer_can_initial_push": false
  },
  "avatar_url": null,
  "request_access_enabled": true,
  "full_name": "test-1",
  "full_path": "test-1",
  "created_at": "2025-03-25T12:05:24.813Z",
  "parent_id": null,
  "organization_id": 1,
  "shared_runners_setting": "enabled",
  "max_artifacts_size": null,
  "ldap_cn": null,
  "ldap_access": null,
  "wiki_access_level": "enabled",
  "shared_with_groups": [],
  "prevent_sharing_groups_outside_hierarchy": false,
  "shared_runners_minutes_limit": null,
  "extra_shared_runners_minutes_limit": null,
  "prevent_forking_outside_group": null,
  "membership_lock": false
}
```

### Transfer a group[](https://docs.gitlab.com/api/groups/#transfer-a-group "Permalink")
Transfers a group to a new parent group or transforms a subgroup into a top-level group.
Prerequisites:
  * You must have the Owner role for the group.
  * If transferring a group, you must have permission to [create a subgroup](https://docs.gitlab.com/user/group/subgroups/#create-a-subgroup) in the new parent group.
  * If transforming a subgroup, you must have [permission to create a top-level group](https://docs.gitlab.com/administration/user_settings/).


```
POST /groups/:id/transfer
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | ID of the group to transfer.
`id` | integer | yes | ID of the group to transfer.
`group_id` | integer | no | ID of the new parent group. If unspecified, the group is transformed into a top-level group.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4/transfer?group_id=7"
```

#### List all locations available for group transfer[](https://docs.gitlab.com/api/groups/#list-all-locations-available-for-group-transfer "Permalink")
Lists all available parent groups to transfer a specified group.
```
GET /groups/:id/transfer_locations
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path of the group to transfer](https://docs.gitlab.com/api/rest/#namespaced-paths).
`search` | string | No | The name of a specific group to search for.
Example request:
shell
```
curl --request GET \
    --url "https://gitlab.example.com/api/v4/groups/1/transfer_locations"
```

Example response:
json
```
[
  {
    "id": 27,
    "web_url": "https://gitlab.example.com/groups/gitlab",
    "name": "GitLab",
    "avatar_url": null,
    "full_name": "GitLab",
    "full_path": "GitLab"
  },
  {
    "id": 31,
    "web_url": "https://gitlab.example.com/groups/foobar",
    "name": "FooBar",
    "avatar_url": null,
    "full_name": "FooBar",
    "full_path": "FooBar"
  }
]
```

#### Transfer a project to a group[](https://docs.gitlab.com/api/groups/#transfer-a-project-to-a-group "Permalink")
  * Tier: Free, Premium, Ultimate
  * Offering: GitLab Self-Managed, GitLab Dedicated


Transfers a project to another group namespace. Alternatively, use the [transfer a project to a new namespace](https://docs.gitlab.com/api/projects/#transfer-a-project-to-a-new-namespace) endpoint instead.
The transfer process may fail if tagged packages exist in the project’s repository.
Prerequisites:
  * You must be an administrator for the instance.


```
POST /groups/:id/projects/:project_id
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path of the target group](https://docs.gitlab.com/api/rest/#namespaced-paths).
`project_id` | integer or string | yes | The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/4/projects/56"
```

### Invite groups[](https://docs.gitlab.com/api/groups/#invite-groups "Permalink")
These endpoints are used to for group invitations. For more information, see [invite a group to a group](https://docs.gitlab.com/user/project/members/sharing_projects_groups/#invite-a-group-to-a-group).
#### Create a group invitation[](https://docs.gitlab.com/api/groups/#create-a-group-invitation "Permalink")
Creates a group invitation that adds a target group to a specified group.
```
POST /groups/:id/share
```

Parameters:
Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path of the target group](https://docs.gitlab.com/api/rest/#namespaced-paths).
`group_id` | integer | yes | The ID of the group to invite.
`group_access` | integer | yes | The default `access_level` to assign to the invited group. Possible values: `5` (Minimal access), `10` (Guest), `15` (Planner), `20` (Reporter), `30` (Developer), `40` (Maintainer), or `50` (Owner).
`expires_at` | date (ISO 8601) | no | The date the group invitation expires.
`member_role_id` | integer | no | The ID of a [custom role](https://docs.gitlab.com/user/custom_roles/#assign-a-custom-role-to-an-invited-group) to assign to the invited group. If defined, `group_access` must match the base role used to create the custom role.
Returns `200` and the group details on success.
#### Delete a group invitation[](https://docs.gitlab.com/api/groups/#delete-a-group-invitation "Permalink")
Deletes a group invitation and removes access to the target group from the specified group.
```
DELETE /groups/:id/share/:group_id
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | The ID or [URL-encoded path of the target group](https://docs.gitlab.com/api/rest/#namespaced-paths).
`group_id` | integer | yes | The ID of the group to disinvite.
Returns `204` and no content on success.
## Update group attributes[](https://docs.gitlab.com/api/groups/#update-group-attributes "Permalink")
History
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/183101) in GitLab 18.0. Feature flag `limit_unique_project_downloads_per_namespace_user` removed.
  * `web_based_commit_signing_enabled` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/193928) in GitLab 18.2 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `use_web_based_commit_signing_enabled`. Disabled by default.
  * `allow_personal_snippets` [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/200575) in GitLab 18.5 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `allow_personal_snippets_setting`. Disabled by default.
  * `allow_personal_snippets` [generally available](https://gitlab.com/gitlab-org/gitlab/-/work_items/583564) in GitLab 18.9. Feature flag `allow_personal_snippets_setting` removed.


The availability of the `web_based_commit_signing_enabled` attribute is controlled by a feature flag. For more information, see the history. This feature is available for testing, but not ready for production use.
Updates the attributes for a specified group.
Prerequisites:
  * You must be an administrator or have the Owner role for the group.


```
PUT /groups/:id
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer | yes | The ID of the group.
`name` | string | no | The name of the group.
`path` | string | no | The path of the group.
`auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group.
`avatar` | mixed | no | Image file for avatar of the group.
`default_branch` | string | no | The [default branch](https://docs.gitlab.com/user/project/repository/branches/default/) name for group’s projects. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/442298) in GitLab 16.11.
`default_branch_protection` | integer | no |  [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/408314) in GitLab 17.0. Use `default_branch_protection_defaults` instead.
`default_branch_protection_defaults` | hash | no |  [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/408314) in GitLab 17.0. For available options, see [Options for `default_branch_protection_defaults`](https://docs.gitlab.com/api/groups/#options-for-default_branch_protection_defaults).
`description` | string | no | The description of the group.
`enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `all` to allow both protocols. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/436618) in GitLab 16.9.
`emails_disabled` | boolean | no | ([Deprecated](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/127899) in GitLab 16.5.) Disable email notifications. Use `emails_enabled` instead.
`emails_enabled` | boolean | no | Enable email notifications.
`lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group.
`mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned.
`prevent_sharing_groups_outside_hierarchy` | boolean | no | See [Prevent group sharing outside the group hierarchy](https://docs.gitlab.com/user/project/members/sharing_projects_groups/#prevent-inviting-groups-outside-the-group-hierarchy). This attribute is only available on top-level groups.
`project_creation_level` | string | no | Determine if developers can create projects in the group. Can be `noone` (No one), `maintainer` (users with the Maintainer role), or `developer` (users with the Developer or Maintainer role).
`request_access_enabled` | boolean | no | Allow users to request member access.
`require_two_factor_authentication` | boolean | no | Require all users in this group to set up two-factor authentication.
`shared_runners_setting` | string | no | See [Options for `shared_runners_setting`](https://docs.gitlab.com/api/groups/#options-for-shared_runners_setting). Enable or disable instance runners for a group’s subgroups and projects.
`share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group.
`step_up_auth_required_oauth_provider` | string | no | OAuth provider required for step-up authentication. Pass empty string to disable. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/556943) in GitLab 18.4. Available when `omniauth_step_up_auth_for_namespace` feature flag is enabled.
`subgroup_creation_level` | string | no | Allowed to [create subgroups](https://docs.gitlab.com/user/group/subgroups/#create-a-subgroup). Can be `owner` (users with the Owner role), or `maintainer` (users with the Maintainer role).
`two_factor_grace_period` | integer | no | Time before Two-factor authentication is enforced (in hours).
`visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`.
`extra_shared_runners_minutes_limit` | integer | no | Can be set by administrators only. Additional compute minutes for this group. GitLab Self-Managed, Premium and Ultimate only.
`file_template_project_id` | integer | no | The ID of a project to load custom file templates from. Premium and Ultimate only.
`membership_lock` | boolean | no | Users cannot be added to projects in this group. Premium and Ultimate only.
`prevent_forking_outside_group` | boolean | no | When enabled, users can not fork projects from this group to external namespaces. Premium and Ultimate only.
`shared_runners_minutes_limit` | integer | no | Can be set by administrators only. Maximum number of monthly compute minutes for this group. Can be `nil` (default; inherit system default), `0` (unlimited), or `> 0`. GitLab Self-Managed, Premium and Ultimate only.
`unique_project_download_limit` | integer | no | Maximum number of unique projects a user can download in the specified time period before they are banned. Available only on top-level groups. Default: 0, Maximum: 10,000. Ultimate only.
`unique_project_download_limit_interval_in_seconds` | integer | no | Time period during which a user can download a maximum amount of projects before they are banned. Available only on top-level groups. Default: 0, Maximum: 864,000 seconds (10 days). Ultimate only.
`unique_project_download_limit_allowlist` | array of strings | no | List of usernames excluded from the unique project download limit. Available only on top-level groups. Default: `[]`, Maximum: 100 usernames. Ultimate only.
`unique_project_download_limit_alertlist` | array of integers | no | List of user IDs that are emailed when the unique project download limit is exceeded. Available only on top-level groups. Default: `[]`, Maximum: 100 user IDs. Ultimate only.
`auto_ban_user_on_excessive_projects_download` | boolean | no | When enabled, users are automatically banned from the group when they download more than the maximum number of unique projects specified by `unique_project_download_limit` and `unique_project_download_limit_interval_in_seconds`. Ultimate only.
`ip_restriction_ranges` | string | no | Comma-separated list of IP addresses or subnet masks to restrict group access. Premium and Ultimate only.
`allowed_email_domains_list` | string | no | Comma-separated list of email address domains to allow group access. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/351494) in 17.4. GitLab Premium and Ultimate only.
`wiki_access_level` | string | no | The wiki access level. Can be `disabled`, `private`, or `enabled`. Premium and Ultimate only.
`duo_availability` | string | no | GitLab Duo availability setting. Valid values are: `default_on`, `default_off`, `never_on`. Note: In the UI, `never_on` is displayed as “Always Off”.
`experiment_features_enabled` | boolean | no | Enable experiment features for this group.
`math_rendering_limits_enabled` | boolean | no | Indicates if math rendering limits are used for this group.
`lock_math_rendering_limits_enabled` | boolean | no | Indicates if math rendering limits are locked for all descendent groups.
`duo_features_enabled` | boolean | no | Indicates whether GitLab Duo features are enabled for this group. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144931) in GitLab 16.10. GitLab Self-Managed, Premium and Ultimate only.
`lock_duo_features_enabled` | boolean | no | Indicates whether the GitLab Duo features enabled setting is enforced for all subgroups. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/144931) in GitLab 16.10. GitLab Self-Managed, Premium and Ultimate only.
`max_artifacts_size` | integer | No | The maximum file size in megabytes for individual job artifacts.
`web_based_commit_signing_enabled` | boolean | No | Enables web-based commit signing for commits created from the GitLab UI. Available only for top-level groups on GitLab SaaS. When enabled for a group, applies to all projects in the group.
`only_allow_merge_if_pipeline_succeeds` | boolean | no | Only allow merging merge requests if the pipeline succeeds. When enabled for a group, applies to all projects in the group. Premium and Ultimate only.
`allow_merge_on_skipped_pipeline` | boolean | no | Allow merging merge requests when the pipeline is skipped. Only applies when `only_allow_merge_if_pipeline_succeeds` is `true`. Premium and Ultimate only.
`only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Only allow merging merge requests when all discussions are resolved. When enabled for a group, applies to all projects in the group. Premium and Ultimate only.
`allow_personal_snippets` | boolean | no | Allow enterprise users in this group to create personal snippets. When disabled, enterprise users are restricted from creating snippets in their personal namespace.
The `projects` and `shared_projects` attributes in the response are deprecated and [scheduled for removal in API v5](https://gitlab.com/gitlab-org/gitlab/-/issues/213797). To get the details of all projects within a group, use either the [list a group’s projects](https://docs.gitlab.com/api/groups/#list-projects) or the [list a group’s shared projects](https://docs.gitlab.com/api/groups/#list-shared-projects) endpoint.
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5?name=Experimental"
```

This endpoint returns a maximum of 100 projects and shared projects. To get the details of all projects in a group, use the [list a group’s projects endpoint](https://docs.gitlab.com/api/groups/#list-projects) instead.
Example response:
json
```
{
  "id": 5,
  "name": "Experimental",
  "path": "h5bp",
  "description": "foo",
  "visibility": "internal",
  "avatar_url": null,
  "web_url": "http://gitlab.example.com/groups/h5bp",
  "request_access_enabled": false,
  "repository_storage": "default",
  "full_name": "Foobar Group",
  "full_path": "h5bp",
  "file_template_project_id": 1,
  "parent_id": null,
  "enabled_git_access_protocol": "all",
  "created_at": "2020-01-15T12:36:29.590Z",
  "prevent_sharing_groups_outside_hierarchy": false,
  "only_allow_merge_if_pipeline_succeeds": false,
  "allow_merge_on_skipped_pipeline": false,
  "only_allow_merge_if_all_discussions_are_resolved": false,
  "allow_personal_snippets": true,
  "projects": [ // Deprecated and will be removed in API v5
    {
      "id": 9,
      "description": "foo",
      "default_branch": "main",
      "tag_list": [], //deprecated, use `topics` instead
      "topics": [],
      "public": false,
      "archived": false,
      "visibility": "internal",
      "ssh_url_to_repo": "git@gitlab.example.com/html5-boilerplate.git",
      "http_url_to_repo": "http://gitlab.example.com/h5bp/html5-boilerplate.git",
      "web_url": "http://gitlab.example.com/h5bp/html5-boilerplate",
      "name": "Html5 Boilerplate",
      "name_with_namespace": "Experimental / Html5 Boilerplate",
      "path": "html5-boilerplate",
      "path_with_namespace": "h5bp/html5-boilerplate",
      "issues_enabled": true,
      "merge_requests_enabled": true,
      "wiki_enabled": true,
      "jobs_enabled": true,
      "snippets_enabled": true,
      "created_at": "2016-04-05T21:40:50.169Z",
      "last_activity_at": "2016-04-06T16:52:08.432Z",
      "shared_runners_enabled": true,
      "creator_id": 1,
      "namespace": {
        "id": 5,
        "name": "Experimental",
        "path": "h5bp",
        "kind": "group"
      },
      "avatar_url": null,
      "star_count": 1,
      "forks_count": 0,
      "open_issues_count": 3,
      "public_jobs": true,
      "shared_with_groups": [],
      "request_access_enabled": false
    }
  ],
  "ip_restriction_ranges": null,
  "math_rendering_limits_enabled": true,
  "lock_math_rendering_limits_enabled": false
}
```

The `prevent_sharing_groups_outside_hierarchy` attribute is present in the response only for top-level groups.
Users of [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `wiki_access_level`, `duo_features_enabled`, `lock_duo_features_enabled`, `duo_availability`, and `experiment_features_enabled` attributes.
### Options for `shared_runners_setting`[](https://docs.gitlab.com/api/groups/#options-for-shared_runners_setting "Permalink")
The `shared_runners_setting` attribute determines whether instance runners are enabled for a group’s subgroups and projects.
Value | Description
---|---
`enabled` | Enables instance runners for all projects and subgroups in this group.
`disabled_and_overridable` | Disables instance runners for all projects and subgroups in this group, but allows subgroups to override this setting.
`disabled_and_unoverridable` | Disables instance runners for all projects and subgroups in this group, and prevents subgroups from overriding this setting.
`disabled_with_override` | (Deprecated. Use `disabled_and_overridable`) Disables instance runners for all projects and subgroups in this group, but allows subgroups to override this setting.
## Update group avatars[](https://docs.gitlab.com/api/groups/#update-group-avatars "Permalink")
Update group avatars.
### Download a group avatar[](https://docs.gitlab.com/api/groups/#download-a-group-avatar "Permalink")
Get a group avatar. This endpoint can be accessed without authentication if the group is publicly accessible.
```
GET /groups/:id/avatar
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | yes | ID of the group.
Example:
shell
```
curl --header "PRIVATE-TOKEN: $GITLAB_LOCAL_TOKEN" \
  --remote-header-name \
  --remote-name \
  --url "https://gitlab.example.com/api/v4/groups/4/avatar"
```

### Upload a group avatar[](https://docs.gitlab.com/api/groups/#upload-a-group-avatar "Permalink")
To upload an avatar file from your file system, use the `--form` argument. This causes curl to post data using the header `Content-Type: multipart/form-data`. The `file=` parameter must point to a file on your file system and be preceded by `@`. For example:
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "avatar=@/tmp/example.png" \
  --url "https://gitlab.example.com/api/v4/groups/22"
```

### Remove a group avatar[](https://docs.gitlab.com/api/groups/#remove-a-group-avatar "Permalink")
To remove a group avatar, use a blank value for the `avatar` attribute.
Example request:
shell
```
curl --request PUT \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "avatar=" \
  --url "https://gitlab.example.com/api/v4/groups/22"
```

## Sync a group with LDAP[](https://docs.gitlab.com/api/groups/#sync-a-group-with-ldap "Permalink")
  * Tier: Premium, Ultimate
  * Offering: GitLab Self-Managed


Syncs a specified group with its linked LDAP group.
Prerequisites:
  * You must be an administrator or have the Owner role for the group.


```
POST /groups/:id/ldap_sync
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or URL-encoded path of a group.
## Credentials inventory management[](https://docs.gitlab.com/api/groups/#credentials-inventory-management "Permalink")
  * Tier: Premium, Ultimate
  * Offering: GitLab.com


History
  * [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/16343) in GitLab 18.6 [with a flag](https://docs.gitlab.com/administration/feature_flags/) named `manage_pat_by_group_owners_ready`. Disabled by default.
  * [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/578133) in GitLab 18.7. Feature flag `manage_pat_by_group_owners_ready` removed.


View, revoke, and rotate the credentials of enterprise users on GitLab.com.
Prerequisites:
  * You must have the Owner role for the group.


### List all personal access tokens for a group[](https://docs.gitlab.com/api/groups/#list-all-personal-access-tokens-for-a-group "Permalink")
Lists all personal access tokens associated with enterprise users in a top-level group.
```
GET /groups/:id/manage/personal_access_tokens
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a group.
`created_after` | datetime (ISO 8601) | No | If defined, returns tokens created after the specified time.
`created_before` | datetime (ISO 8601) | No | If defined, returns tokens created before the specified time.
`last_used_after` | datetime (ISO 8601) | No | If defined, returns tokens last used after the specified time.
`last_used_before` | datetime (ISO 8601) | No | If defined, returns tokens last used before the specified time.
`revoked` | boolean | No | If `true`, only returns revoked tokens.
`search` | string | No | If defined, returns tokens that include the specified value in the name.
`state` | string | No | If defined, returns tokens with the specified state. Possible values: `active` and `inactive`.
`sort` | string | No | If defined, sorts the results by the specified value. Possible values: `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, `name_desc`.
Example request:
shell
```
curl --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens"
```

Example response:
json
```
[
  {
    "id": 1,
    "name": "Test Token",
    "revoked": false,
    "created_at": "2020-07-23T14:31:47.729Z",
    "description": "Test Token description",
    "scopes": [
        "api"
    ],
    "user_id": 3,
    "last_used_at": "2021-10-06T17:58:37.550Z",
    "active": true,
    "expires_at": "2025-11-08"
  }
]
```

### List all group and project access tokens for a group[](https://docs.gitlab.com/api/groups/#list-all-group-and-project-access-tokens-for-a-group "Permalink")
Lists all group and project access tokens associated with a top-level-group.
```
GET /groups/:id/manage/resource_access_tokens
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a group.
`created_after` | datetime (ISO 8601) | No | If defined, returns tokens created after the specified time.
`created_before` | datetime (ISO 8601) | No | If defined, returns tokens created before the specified time.
`last_used_after` | datetime (ISO 8601) | No | If defined, returns tokens last used after the specified time.
`last_used_before` | datetime (ISO 8601) | No | If defined, returns tokens last used before the specified time.
`revoked` | boolean | No | If `true`, only returns revoked tokens.
`search` | string | No | If defined, returns tokens that include the specified value in the name.
`state` | string | No | If defined, returns tokens with the specified state. Possible values: `active` and `inactive`.
`sort` | string | No | If defined, sorts the results by the specified value. Possible values: `created_asc`, `created_desc`, `expires_asc`, `expires_desc`, `last_used_asc`, `last_used_desc`, `name_asc`, `name_desc`.
Example request:
shell
```
curl --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens"
```

Example response:
json
```
[
  {
    "id": 12767703,
    "name": "Test Group Token",
    "revoked": false,
    "created_at": "2025-01-07T00:25:02.128Z",
    "description": "",
    "scopes": [
        "read_registry"
    ],
    "user_id": 25365147,
    "last_used_at": null,
    "active": true,
    "expires_at": "2025-06-19",
    "access_level": 10,
    "resource_type": "group",
    "resource_id": 77449520
  }
]
```

### List all SSH keys for a group[](https://docs.gitlab.com/api/groups/#list-all-ssh-keys-for-a-group "Permalink")
Lists all SSH public keys associated with enterprise users in a top-level-group.
```
GET /groups/:id/manage/ssh_keys
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | The ID or [URL-encoded path](https://docs.gitlab.com/api/rest/#namespaced-paths) of a group.
`created_after` | datetime (ISO 8601) | No | If defined, returns SSH keys created after the specified time.
`created_before` | datetime (ISO 8601) | No | If defined, returns SSH keys created before the specified time.
`expires_before` | datetime (ISO 8601) | No | If defined, returns SSH keys that expire before the specified time.
`expires_after` | datetime (ISO 8601) | No | If defined, returns SSH keys that expire after the specified time.
shell
```
curl --header "PRIVATE-TOKEN: <group_owner_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/ssh_keys"
```

Example response:
json
```
[
  {
    "id":3,
    "title":"Sample key 3",
    "created_at":"2024-12-23T05:40:11.891Z",
    "expires_at":null,
    "last_used_at":"2024-12-23T05:40:11.891Z",
    "usage_type":"auth_and_signing",
    "user_id":3
  }
]
```

### Revoke a personal access token for an enterprise user[](https://docs.gitlab.com/api/groups/#revoke-a-personal-access-token-for-an-enterprise-user "Permalink")
Revokes a specified personal access token for an enterprise user.
```
DELETE groups/:id/manage/personal_access_tokens/:id
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | ID of a personal access token or the keyword `self`.
shell
```
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/personal_access_tokens/<personal_access_token_id>"
```

If successful, returns `204: No Content`.
Other possible responses:
  * `400: Bad Request` if not revoked successfully.
  * `401: Unauthorized` if the access token is invalid.
  * `403: Forbidden` if the access token does not have the required permissions.


### Revoke a group or project access token for an enterprise user[](https://docs.gitlab.com/api/groups/#revoke-a-group-or-project-access-token-for-an-enterprise-user "Permalink")
Revokes a specified group or project access token for an enterprise user associated with the top-level group.
```
DELETE groups/:id/manage/resource_access_tokens/:id
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | ID of a resource access token or the keyword `self`.
shell
```
curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/1/manage/resource_access_tokens/<personal_access_token_id>"
```

If successful, returns `204: No Content`.
Other possible responses:
  * `400: Bad Request` if not revoked successfully.
  * `401: Unauthorized` if the access token is invalid.
  * `403: Forbidden` if the access token does not have the required permissions.


### Delete an SSH key for an enterprise user[](https://docs.gitlab.com/api/groups/#delete-an-ssh-key-for-an-enterprise-user "Permalink")
Deletes a specified SSH public key for an enterprise user associated with the top-level group.
```
DELETE /groups/:id/manage/ssh_keys/:key_id
```

Supported attributes:
Attribute | Type | Required | Description
---|---|---|---
`key_id` | integer | Yes | ID of existing key.
If successful, returns `204: No Content`.
Other possible responses:
  * `400: Bad Request` if SSH Key is not deleted successfully.
  * `401: Unauthorized` if the SSH Key is invalid.
  * `403: Forbidden` if the user does not have the required permissions.


### Rotate a personal access token for an enterprise user[](https://docs.gitlab.com/api/groups/#rotate-a-personal-access-token-for-an-enterprise-user "Permalink")
Rotates a specified personal access token for an enterprise user associated with the top-level group. This revokes the previous token and creates a new token that expires after one week.
```
POST groups/:id/manage/personal_access_tokens/:id/rotate
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | ID of a personal access token or the keyword `self`.
`expires_at` | date | No | Expiration date of the access token in ISO format (`YYYY-MM-DD`). The date must be one year or less from the rotation date. If undefined, the token expires after one week.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/personal_access_tokens/<personal_access_token_id>/rotate"
```

Example response:
json
```
{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}
```

If successful, returns `200: OK`.
Other possible responses:
  * `400: Bad Request` if not rotated successfully.
  * `401: Unauthorized` if any of the following conditions are true:
    * The token does not exist.
    * The token has expired.
    * The token was revoked.
    * You do not have access to the specified token.
  * `403: Forbidden` if the token is not allowed to rotate itself.
  * `404: Not Found` if the user has the Owner role, but the token does not exist.
  * `405: Method Not Allowed` if the token is not a personal access token.


### Rotate a group or project access token for an enterprise user[](https://docs.gitlab.com/api/groups/#rotate-a-group-or-project-access-token-for-an-enterprise-user "Permalink")
Rotates a specified group or project access token for an enterprise user associated with the top-level group. This revokes the previous token and creates a new token that expires after one week.
```
POST groups/:id/manage/resource_access_tokens/:id/rotate
```

Attribute | Type | Required | Description
---|---|---|---
`id` | integer or string | Yes | ID of a personal access token or the keyword `self`.
`expires_at` | date | No | Expiration date of the access token in ISO format (`YYYY-MM-DD`). The date must be one year or less from the rotation date. If undefined, the token expires after one week.
shell
```
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/:id/manage/resource_access_tokens/<resource_access_token_id>/rotate"
```

Example response:
json
```
{
    "id": 42,
    "name": "Rotated Token",
    "revoked": false,
    "created_at": "2023-08-01T15:00:00.000Z",
    "description": "Test Token description",
    "scopes": ["api"],
    "user_id": 1337,
    "last_used_at": null,
    "active": true,
    "expires_at": "2023-08-15",
    "token": "s3cr3t"
}
```

If successful, returns `200: OK`.
Other possible responses:
  * `400: Bad Request` if not rotated successfully.
  * `401: Unauthorized` if any of the following conditions are true:
    * The token does not exist.
    * The token has expired.
    * The token was revoked.
    * You do not have access to the specified token.
  * `403: Forbidden` if the token is not allowed to rotate itself or token is not a bot user token.
  * `404: Not Found` if the user has the Owner role, but the token does not exist.


Was this page helpful?YesNo
Edit this page
  *     * [ Open in Web IDE`.`Quickly and easily edit multiple files. ](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/groups.md)
    * [ View page sourceEdit this file only. ](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/groups.md)
    * [ Create an issueSuggest improvements. ](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


  * [Retrieve a group](https://docs.gitlab.com/api/groups/#retrieve-a-group)
  * [List groups](https://docs.gitlab.com/api/groups/#list-groups)
  * [List all groups](https://docs.gitlab.com/api/groups/#list-all-groups)
  * [Group pagination](https://docs.gitlab.com/api/groups/#group-pagination)
  * [Search for a group](https://docs.gitlab.com/api/groups/#search-for-a-group)
  * [List group details](https://docs.gitlab.com/api/groups/#list-group-details)
  * [List projects](https://docs.gitlab.com/api/groups/#list-projects)
  * [List shared projects](https://docs.gitlab.com/api/groups/#list-shared-projects)
  * [List all SAML users](https://docs.gitlab.com/api/groups/#list-all-saml-users)
  * [List provisioned users](https://docs.gitlab.com/api/groups/#list-provisioned-users)
  * [List subgroups](https://docs.gitlab.com/api/groups/#list-subgroups)
  * [List descendant groups](https://docs.gitlab.com/api/groups/#list-descendant-groups)
  * [List shared groups](https://docs.gitlab.com/api/groups/#list-shared-groups)
  * [List invited groups](https://docs.gitlab.com/api/groups/#list-invited-groups)
  * [List audit events](https://docs.gitlab.com/api/groups/#list-audit-events)
  * [Manage groups](https://docs.gitlab.com/api/groups/#manage-groups)
  * [Create a group](https://docs.gitlab.com/api/groups/#create-a-group)
  * [Options for default_branch_protection](https://docs.gitlab.com/api/groups/#options-for-default_branch_protection)
  * [Options for default_branch_protection_defaults](https://docs.gitlab.com/api/groups/#options-for-default_branch_protection_defaults)
  * [Create a subgroup](https://docs.gitlab.com/api/groups/#create-a-subgroup)
  * [Schedule a group for deletion](https://docs.gitlab.com/api/groups/#schedule-a-group-for-deletion)
  * [Delete a group permanently](https://docs.gitlab.com/api/groups/#delete-a-group-permanently)
  * [Restore a group marked for deletion](https://docs.gitlab.com/api/groups/#restore-a-group-marked-for-deletion)
  * [Archive a group](https://docs.gitlab.com/api/groups/#archive-a-group)
  * [Unarchive a group](https://docs.gitlab.com/api/groups/#unarchive-a-group)
  * [Transfer a group](https://docs.gitlab.com/api/groups/#transfer-a-group)
  * [List all locations available for group transfer](https://docs.gitlab.com/api/groups/#list-all-locations-available-for-group-transfer)
  * [Transfer a project to a group](https://docs.gitlab.com/api/groups/#transfer-a-project-to-a-group)
  * [Invite groups](https://docs.gitlab.com/api/groups/#invite-groups)
  * [Create a group invitation](https://docs.gitlab.com/api/groups/#create-a-group-invitation)
  * [Delete a group invitation](https://docs.gitlab.com/api/groups/#delete-a-group-invitation)
  * [Update group attributes](https://docs.gitlab.com/api/groups/#update-group-attributes)
  * [Options for shared_runners_setting](https://docs.gitlab.com/api/groups/#options-for-shared_runners_setting)
  * [Update group avatars](https://docs.gitlab.com/api/groups/#update-group-avatars)
  * [Download a group avatar](https://docs.gitlab.com/api/groups/#download-a-group-avatar)
  * [Upload a group avatar](https://docs.gitlab.com/api/groups/#upload-a-group-avatar)
  * [Remove a group avatar](https://docs.gitlab.com/api/groups/#remove-a-group-avatar)
  * [Sync a group with LDAP](https://docs.gitlab.com/api/groups/#sync-a-group-with-ldap)
  * [Credentials inventory management](https://docs.gitlab.com/api/groups/#credentials-inventory-management)
  * [List all personal access tokens for a group](https://docs.gitlab.com/api/groups/#list-all-personal-access-tokens-for-a-group)
  * [List all group and project access tokens for a group](https://docs.gitlab.com/api/groups/#list-all-group-and-project-access-tokens-for-a-group)
  * [List all SSH keys for a group](https://docs.gitlab.com/api/groups/#list-all-ssh-keys-for-a-group)
  * [Revoke a personal access token for an enterprise user](https://docs.gitlab.com/api/groups/#revoke-a-personal-access-token-for-an-enterprise-user)
  * [Revoke a group or project access token for an enterprise user](https://docs.gitlab.com/api/groups/#revoke-a-group-or-project-access-token-for-an-enterprise-user)
  * [Delete an SSH key for an enterprise user](https://docs.gitlab.com/api/groups/#delete-an-ssh-key-for-an-enterprise-user)
  * [Rotate a personal access token for an enterprise user](https://docs.gitlab.com/api/groups/#rotate-a-personal-access-token-for-an-enterprise-user)
  * [Rotate a group or project access token for an enterprise user](https://docs.gitlab.com/api/groups/#rotate-a-group-or-project-access-token-for-an-enterprise-user)


[![GitLab Docs logo](https://docs.gitlab.com/gitlab-logo-footer.svg)](https://docs.gitlab.com/)
  * [Facebook](https://www.facebook.com/gitlab)
  * [LinkedIn](https://www.linkedin.com/company/gitlab-com)
  * [Twitter](https://twitter.com/gitlab)
  * [YouTube](https://www.youtube.com/channel/UCnMGQ8QHMAnVIsI3xJrihhg)

[![Creative Commons License](https://docs.gitlab.com/by-sa.svg)](https://creativecommons.org/licenses/by-sa/4.0/)
Company
  * [About GitLab](https://about.gitlab.com/company/)
  * [View pricing](https://about.gitlab.com/pricing/)
  * [Try GitLab for free](https://about.gitlab.com/free-trial/)


Feedback
  * [View page source](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/api/groups.md)
  * [Edit in Web IDE](https://gitlab.com/-/ide/project/gitlab-org/gitlab/edit/master/-/doc/api/groups.md)
  * [Contribute to GitLab](https://about.gitlab.com/community/contribute/)
  * [Suggest updates](https://gitlab.com/gitlab-org/gitlab/-/issues/new?issuable_template=Documentation)


Help & Community
  * [Get certified](https://university.gitlab.com/pages/certifications)
  * [Get support](https://about.gitlab.com/support/)
  * [Post on the GitLab forum](https://forum.gitlab.com/new-topic?title=topic%20title&body=topic%20body&tags=docs-feedback)


Resources
  * [Terms](https://about.gitlab.com/terms/)
  * [Privacy statement](https://about.gitlab.com/privacy/)
  * [Use of generative AI](https://docs.gitlab.com/legal/use_generative_ai/)
  * [Acceptable use of user licenses](https://docs.gitlab.com/legal/licensing_policy/)
  * Cookie Preferences


![](https://cdn.bizible.com/ipv?_biz_r=&_biz_h=800054037&_biz_u=10503924d6784ad3f2d352558587a67a&_biz_l=https%3A%2F%2Fdocs.gitlab.com%2Fapi%2Fgroups%2F&_biz_t=1772174296309&_biz_i=Groups%20API%20%7C%20GitLab%20Docs&_biz_n=72&rnd=661917&cdn_o=a&_biz_z=1772174296319)
![Company Logo](https://cdn.cookielaw.org/logos/aa14a5c8-79e3-442a-8177-464ad850b19d/e46c1d0d-1f66-481f-bc06-5427671431da/253e6fee-c4c0-4b60-bc35-79cdae5dda32/gitlab-logo-100.png)
## Privacy Preference Center
## Privacy Preference Center
  * ### Your Privacy
  * ### Strictly Necessary Cookies
  * ### Functionality Cookies
  * ### Performance and Analytics Cookies
  * ### Targeting and Advertising Cookies
  * ### Ad User Data
  * ### Ad Personalization


#### Your Privacy
When you visit any website, it may store or retrieve information on your browser, mostly in the form of cookies. This information might be about you, your preferences or your device and is mostly used to make the site work as you expect it to. The information does not usually directly identify you, but it can give you a more personalized web experience. Because we respect your right to privacy, you can choose not to allow some types of cookies. Click on the different category headings to find out more and change our default settings. However, blocking some types of cookies may impact your experience of the site and the services we are able to offer.
[Cookie Policy](https://about.gitlab.com/privacy/cookies/)
**User ID:** 42fad8d5-ed56-4786-8d74-3c72635252d2
_This User ID will be used as a unique identifier while storing and accessing your preferences for future._
**Timestamp:** --
#### Strictly Necessary Cookies
Always Active
These cookies are necessary for the website to function and cannot be switched off in our systems. They are usually only set in response to actions made by you which amount to a request for services, such as setting your privacy preferences, enabling you to securely log into the site, filling in forms, or using the customer checkout. GitLab processes any personal data collected through these cookies on the basis of our legitimate interest.
Cookies Details
#### Functionality Cookies
Functionality Cookies
These cookies enable helpful but non-essential website functions that improve your website experience. By recognizing you when you return to our website, they may, for example, allow us to personalize our content for you or remember your preferences. If you do not allow these cookies then some or all of these services may not function properly. GitLab processes any personal data collected through these cookies on the basis of your consent
Cookies Details
#### Performance and Analytics Cookies
Performance and Analytics Cookies
These cookies allow us and our third-party service providers to recognize and count the number of visitors on our websites and to see how visitors move around our websites when they are using it. This helps us improve our products and ensures that users can easily find what they need on our websites. These cookies usually generate aggregate statistics that are not associated with an individual. To the extent any personal data is collected through these cookies, GitLab processes that data on the basis of your consent.
Cookies Details
#### Targeting and Advertising Cookies
Targeting and Advertising Cookies
These cookies enable different advertising related functions. They may allow us to record information about your visit to our websites, such as pages visited, links followed, and videos viewed so we can make our websites and the advertising displayed on it more relevant to your interests. They may be set through our website by our advertising partners. They may be used by those companies to build a profile of your interests and show you relevant advertisements on other websites. GitLab processes any personal data collected through these cookies on the basis of your consent.
Cookies Details
#### Ad User Data
Ad User Data
Sets consent for sending user data to Google for advertising purposes.
Cookies Details
#### Ad Personalization
Ad Personalization
Sets consent for personalized advertising.
Cookies Details
Back Button
### Cookie List
Filter Button
Consent Leg.Interest
checkbox label label
checkbox label label
checkbox label label
Clear
  * checkbox label label


Apply Cancel
Confirm My Choices
Allow All
[![Powered by Onetrust](https://cdn.cookielaw.org/logos/static/powered_by_logo.svg)](https://www.onetrust.com/products/cookie-consent/)
