> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Permission Groups

> Every group in your workspace, including the All group.

Returns the groups in your workspace, paginated. This is where a group's `id` comes from when you want to grant to it or change who is in it.

## Query parameters

| Parameter   | Type    | Description                                                                                                                                                       |
| ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search`    | string  | Match on group name or description.                                                                                                                               |
| `users`     | integer | Only groups this user belongs to. Takes a user id, not a UUID.                                                                                                    |
| `page`      | integer | Page number.                                                                                                                                                      |
| `page_size` | integer | Results per page.                                                                                                                                                 |
| `expand[]`  | string  | `users`, `user_count`, `lakehouse_permissions`, `object_permissions`, `semantic_layer_permissions`. See [Expanding Responses](/platform-api/expanding-responses). |

<Tip>
  `users` answers "which groups is this person in", which is the fastest way to audit somebody's inherited access before you change it.
</Tip>

## Response

A paginated list of [permission group objects](/platform-api/permission-groups/permission-group).

```json theme={null}
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "b8c5e1e3-6d02-4f45-ad20-8f4b6e2d0e13",
      "name": "All",
      "description": "Everyone in the workspace",
      "all_group": true,
      "created_at": "2026-01-14T09:02:11Z",
      "updated_at": "2026-01-14T09:02:11Z",
      "users": [7, 12, 42]
    },
    {
      "id": "c1f0a9d4-5b62-4e18-9a73-2d8e4f6b0c51",
      "name": "Analysts",
      "description": "Read access to the Gold layer",
      "all_group": false,
      "created_at": "2026-03-02T14:20:55Z",
      "updated_at": "2026-09-18T11:47:03Z",
      "users": [12, 42]
    }
  ]
}
```

<Note>
  Exactly one group has `all_group: true`, and it contains every member automatically. See [the All group](/platform-api/permission-groups/overview#the-all-group) for what you can and cannot do to it.
</Note>

## Find a group by name

```python theme={null}
import os

import requests

BASE_URL = "https://api.nekt.ai"
headers = {"x-api-key": os.environ["NEKT_API_KEY"]}

response = requests.get(
    f"{BASE_URL}/api/v1/organization/permission-groups/",
    headers=headers,
    params={"search": "Analysts"},
)
response.raise_for_status()

for group in response.json()["results"]:
    print(f"{group['name']}: {group['id']}")
```

## Related

* [Create a Group](/platform-api/permission-groups/create) — when the one you want does not exist.
* [List Members](/platform-api/permission-groups/members) — who is in one.
* [List Recipients](/platform-api/permissions/catalog/recipients) — the picker view, filtered by what can still be granted.


## OpenAPI

````yaml GET /api/v1/organization/permission-groups/
openapi: 3.0.3
info:
  title: Nekt API
  version: v1
  description: Nekt API Documentation
  contact:
    email: support@nekt.ai
servers:
  - url: https://api.nekt.ai
security: []
paths:
  /api/v1/organization/permission-groups/:
    get:
      tags:
        - v1
      summary: List permission groups
      operationId: v1_organization_permission_groups_list
      parameters:
        - name: page
          required: false
          in: query
          description: A page number within the paginated result set.
          schema:
            type: integer
        - name: page_size
          required: false
          in: query
          description: Number of results to return per page.
          schema:
            type: integer
        - name: search
          required: false
          in: query
          description: A search term.
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedPermissionGroupList'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    PaginatedPermissionGroupList:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          example: 123
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/PermissionGroup'
    PermissionGroup:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        name:
          type: string
          maxLength: 150
        description:
          type: string
          nullable: true
        all_group:
          type: boolean
          readOnly: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        users:
          type: array
          items:
            type: integer
          description: Users (Expandable)
      required:
        - all_group
        - created_at
        - id
        - name
        - updated_at
        - users
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API Key authentication. Format: ''x-api-key: api_key'''

````