> ## 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.

# Retrieve a Permission Group

> One group, with its membership and the grants it holds.

Reads a single group. Expanded, this is the fastest way to answer "what does this team have access to", because a group's grants are listed on all three axes at once.

## Query parameters

| Parameter  | Type   | Description                                                                                                                                                       |
| ---------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `expand[]` | string | `users`, `user_count`, `lakehouse_permissions`, `object_permissions`, `semantic_layer_permissions`. See [Expanding Responses](/platform-api/expanding-responses). |

## Audit a team's access

```bash theme={null}
curl --request GET \
  --url "https://api.nekt.ai/api/v1/organization/permission-groups/GROUP_ID/?expand[]=users&expand[]=lakehouse_permissions&expand[]=object_permissions&expand[]=semantic_layer_permissions" \
  --header "x-api-key: YOUR_API_KEY"
```

The three permission fields list only the grants held **directly by the group**. A member of the group may reach more than this through their own grants or another group — a person's effective access is the union of everything that reaches them.

## Response

A [permission group object](/platform-api/permission-groups/permission-group).

```json theme={null}
{
  "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]
}
```

## Errors

| Status | When                                     |
| ------ | ---------------------------------------- |
| `404`  | No group with that id in your workspace. |

## Related

* [List Groups](/platform-api/permission-groups/list) — where the id comes from.
* [List Members](/platform-api/permission-groups/members) — the membership on its own.
* [Permissions flow](/platform-api/permissions/overview) — reading grants by recipient instead.


## OpenAPI

````yaml GET /api/v1/organization/permission-groups/{id}/
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/{id}/:
    get:
      tags:
        - v1
      summary: Retrieve a permission group
      operationId: v1_organization_permission_groups_retrieve
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: The permission group's id.
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionGroup'
          description: ''
      security:
        - ApiKeyAuth: []
components:
  schemas:
    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'''

````