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

# List readable employee groups

> Lists non-archived employee groups that you can read. Filter by name, type, source, category, sharing, creator, integration, external group type, or employee count. categoryId and externalType accept one value or repeated query parameters. A group can match any selected category; includeUncategorized also includes groups without an active category. All other supplied filters must match. Pages start at 1; pageSize defaults to 50 and is limited to 100. Request include.total for the matching count; otherwise the count is omitted. Continue while pagination.hasMore is true. Groups are sorted by name ascending, then ID, unless another sort is requested.



## OpenAPI

````yaml https://api.gowindmill.com/api/v2/openapi.json get /c/{companyId}/groups
openapi: 3.1.0
info:
  title: Windmill API
  version: 2.0.0
  description: >-
    Use the Windmill API to integrate your systems, automate workflows, and
    build applications on your organization's data. Authenticate with an API key
    or OAuth access token. Each request uses the authenticated user's
    permissions within the selected workspace.
servers:
  - url: https://api.gowindmill.com/api/v2
security:
  - bearerAuth: []
paths:
  /c/{companyId}/groups:
    get:
      tags:
        - Groups
      summary: List readable employee groups
      description: >-
        Lists non-archived employee groups that you can read. Filter by name,
        type, source, category, sharing, creator, integration, external group
        type, or employee count. categoryId and externalType accept one value or
        repeated query parameters. A group can match any selected category;
        includeUncategorized also includes groups without an active category.
        All other supplied filters must match. Pages start at 1; pageSize
        defaults to 50 and is limited to 100. Request include.total for the
        matching count; otherwise the count is omitted. Continue while
        pagination.hasMore is true. Groups are sorted by name ascending, then
        ID, unless another sort is requested.
      operationId: groups.list
      parameters:
        - schema:
            type: string
            minLength: 1
            maxLength: 128
            description: >-
              Company ID. A URL slug is also accepted. The caller must have
              access to this company.
            title: Company ID
            example: company-acme
          required: true
          description: >-
            Company ID. A URL slug is also accepted. The caller must have access
            to this company.
          name: companyId
          in: path
        - schema:
            type: string
            description: >-
              Optional search text. Group and category names use a
              case-insensitive substring match.
            title: Search text
            example: Engineering
          required: false
          description: >-
            Optional search text. Group and category names use a
            case-insensitive substring match.
          name: query
          in: query
        - schema:
            type: string
            enum:
              - MANUAL
              - FILTER
              - SYNCED
              - SCIM
            description: >-
              MANUAL has an explicit roster; FILTER uses employee rules; SYNCED
              follows an integration group; SCIM is provisioned.
            title: Group type
            example: MANUAL
          required: false
          description: >-
            MANUAL has an explicit roster; FILTER uses employee rules; SYNCED
            follows an integration group; SCIM is provisioned.
          name: type
          in: query
        - schema:
            type: array
            items:
              type: string
              format: uuid
            description: >-
              One or more category UUIDs. Matching any selected category is
              sufficient.
            title: Category filter
            example:
              - 11111111-1111-4111-8111-111111111111
          required: false
          description: >-
            One or more category UUIDs. Matching any selected category is
            sufficient.
          name: categoryId
          in: query
        - schema:
            type: string
            description: >-
              Include groups with no active categories, combined with categoryId
              by OR.
            title: Include uncategorized
            example: 'true'
          required: false
          description: >-
            Include groups with no active categories, combined with categoryId
            by OR.
          name: includeUncategorized
          in: query
        - schema:
            type: array
            items:
              type: string
            description: >-
              Integration-defined group type. The group list accepts a single
              value or repeated values.
            title: External type filter
          required: false
          description: >-
            Integration-defined group type. The group list accepts a single
            value or repeated values.
          name: externalType
          in: query
        - schema:
            type: string
            enum:
              - windmill
              - scim
              - integration
            description: >-
              windmill selects MANUAL/FILTER groups; scim selects SCIM;
              integration selects SYNCED groups.
            title: Group source
            example: windmill
          required: false
          description: >-
            windmill selects MANUAL/FILTER groups; scim selects SCIM;
            integration selects SYNCED groups.
          name: source
          in: query
        - schema:
            type: string
            description: >-
              Owning integration identifier, or null for groups without an
              integration link.
            title: Integration ID
          required: false
          description: >-
            Owning integration identifier, or null for groups without an
            integration link.
          name: integrationId
          in: query
        - schema:
            type: string
            enum:
              - company
              - restricted
            description: >-
              company selects company-wide or global read access; restricted
              selects other readable groups.
            title: Sharing filter
            example: company
          required: false
          description: >-
            company selects company-wide or global read access; restricted
            selects other readable groups.
          name: visibility
          in: query
        - schema:
            type: string
            description: >-
              Employee who created this resource, or null when no employee
              creator is recorded.
            title: Creator employee ID
          required: false
          description: >-
            Employee who created this resource, or null when no employee creator
            is recorded.
          name: createdByEmployeeId
          in: query
        - schema:
            type: string
            enum:
              - lt
              - lte
              - eq
              - gt
              - gte
            description: Comparison applied to memberCount. Supply both fields together.
            title: Member count comparison
            example: gte
          required: false
          description: Comparison applied to memberCount. Supply both fields together.
          name: memberCountOperator
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            description: >-
              Nonnegative member count threshold. Supply memberCountOperator
              with this value.
            title: Member count
            example: 1
          required: false
          description: >-
            Nonnegative member count threshold. Supply memberCountOperator with
            this value.
          name: memberCount
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 90071992547409
            default: 1
            description: One-based page number. Defaults to 1.
            title: Page number
            example: 1
          required: false
          description: One-based page number. Defaults to 1.
          name: page
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            description: Maximum results per page, from 1 to 100. Defaults to 50.
            title: Page size
            example: 50
          required: false
          description: Maximum results per page, from 1 to 100. Defaults to 50.
          name: pageSize
          in: query
        - schema:
            type: object
            properties:
              total:
                type: boolean
                description: >-
                  Set true to count all matching items and include
                  pagination.total. False or omission skips the count.
                title: Include total count
                example: true
            description: >-
              Request total:true to include pagination.total; otherwise no count
              is performed.
            title: Additional response details
            example:
              total: true
          required: false
          description: >-
            Request total:true to include pagination.total; otherwise no count
            is performed.
          style: deepObject
          explode: true
          name: include
          in: query
        - schema:
            $ref: '#/components/schemas/EmployeeGroupSortProperty'
          required: false
          description: >-
            Field used to order results. Supported values depend on this
            listing. Defaults to name.
          name: sortProperty
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: asc
            description: Ascending or descending order. Defaults to asc.
            title: Sort direction
            example: asc
          required: false
          description: Ascending or descending order. Defaults to asc.
          name: sortDirection
          in: query
      responses:
        '200':
          description: List employee groups.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEmployeeGroupsResponse'
        '400':
          description: Bad request or request validation failed
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - BAD_REQUEST
                          message:
                            type: string
                          requestId:
                            type: string
                        required:
                          - code
                          - message
                          - requestId
                    required:
                      - error
                  - type: object
                    properties:
                      error:
                        type: object
                        properties:
                          code:
                            type: string
                            enum:
                              - VALIDATION_ERROR
                          message:
                            type: string
                          requestId:
                            type: string
                          details:
                            type: array
                            items:
                              type: object
                              properties:
                                path:
                                  type: array
                                  items:
                                    anyOf:
                                      - type: string
                                      - type: number
                                message:
                                  type: string
                              required:
                                - path
                                - message
                        required:
                          - code
                          - message
                          - requestId
                          - details
                    required:
                      - error
        '401':
          description: >-
            Authentication is missing or invalid. Send a valid API key or OAuth
            access token in the Authorization: Bearer <TOKEN> header before
            retrying.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - UNAUTHORIZED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - FORBIDDEN
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - NOT_FOUND
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
        '429':
          description: >-
            The API-client request budget is exhausted. API keys allow 500
            requests per minute per key; OAuth clients allow 500 per minute per
            client and workspace. Reads and writes share the budget. One HTTP
            request counts once, including bulk requests. Wait for the
            Retry-After delay before retrying.
          headers:
            Retry-After:
              description: Number of seconds to wait before retrying the request.
              required: true
              schema:
                type: integer
                minimum: 0
                example: 42
            RateLimit:
              description: >-
                Current request budget: limit is the maximum count, remaining is
                the unused count, and reset is seconds until the window resets,
                not a timestamp.
              required: true
              schema:
                type: string
                example: limit=500, remaining=0, reset=42
            RateLimit-Policy:
              description: >-
                Request limit and window length in seconds, formatted as
                <limit>;w=<seconds>.
              required: true
              schema:
                type: string
                example: 500;w=60
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - RATE_LIMITED
                      message:
                        type: string
                      requestId:
                        type: string
                    required:
                      - code
                      - message
                      - requestId
                required:
                  - error
      security:
        - bearerAuth: []
components:
  schemas:
    EmployeeGroupSortProperty:
      type: string
      enum:
        - name
        - employeeCount
        - externalType
        - createdAt
        - updatedAt
      default: name
      title: Sort field
      description: >-
        Field used to order results. Supported values depend on this listing.
        Defaults to name.
      example: name
    ListEmployeeGroupsResponse:
      type: object
      properties:
        groups:
          type: array
          items:
            $ref: '#/components/schemas/EmployeeGroupV3'
          description: Matching groups in the requested page, or an empty array.
          title: Groups
          example: []
        pagination:
          $ref: '#/components/schemas/EmployeeGroupPagination'
      required:
        - groups
        - pagination
      title: Employee group list
      description: Readable group page, continuation flag, and optional matching count.
      example:
        groups:
          - id: group-engineering
            name: Engineering
            type: MANUAL
            categoryIds:
              - 11111111-1111-4111-8111-111111111111
            employeeCount: 1
            integrationId: null
            integrationUserGroupId: null
            integrationUserGroupExternalType: null
            createdByEmployeeId: employee-avery
            createdAt: '2026-01-15T10:00:00.000Z'
            updatedAt: '2026-01-15T10:00:00.000Z'
            sharingAccess:
              companyAccess: read
              allManagersAccess: none
              employeeAccess:
                - employeeId: employee-avery
                  access: write
              groupAccess: []
              subtreeAccess: []
            canWrite: true
        pagination:
          page: 1
          pageSize: 50
          hasMore: false
          total: 1
    EmployeeGroupV3:
      type: object
      properties:
        id:
          type: string
          description: Opaque employee group identifier in this company.
          title: Employee group ID
          example: group-engineering
        name:
          type: string
          description: Employee group display name.
          title: Group name
          example: Engineering
        type:
          type: string
          enum:
            - MANUAL
            - FILTER
            - SYNCED
            - SCIM
          description: >-
            MANUAL has an explicit roster; FILTER uses employee rules; SYNCED
            follows an integration group; SCIM is provisioned.
          title: Group type
          example: MANUAL
        categoryIds:
          type: array
          items:
            type: string
          description: >-
            Active category UUIDs assigned to the group. A group can belong to
            multiple categories.
          title: Category IDs
          example:
            - 11111111-1111-4111-8111-111111111111
        employeeCount:
          type: number
          description: >-
            Number of non-archived employees currently in this group,
            independently of workspace membership.
          title: Employee count
          example: 1
        integrationId:
          type:
            - string
            - 'null'
          description: >-
            Owning integration identifier, or null for groups without an
            integration link.
          title: Integration ID
        integrationUserGroupId:
          type:
            - string
            - 'null'
          description: >-
            Identifier of the linked integration group, or null when no such
            link exists.
          title: Integration group ID
        integrationUserGroupExternalType:
          type:
            - string
            - 'null'
          description: Integration-defined group type, or null when unavailable.
          title: External group type
        createdByEmployeeId:
          type:
            - string
            - 'null'
          description: >-
            Employee who created this resource, or null when no employee creator
            is recorded.
          title: Creator employee ID
        createdAt:
          type: string
          format: date-time
          description: Creation timestamp in ISO 8601 format.
          title: Created at
          example: '2026-01-15T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: Last recorded update timestamp in ISO 8601 format.
          title: Updated at
          example: '2026-01-15T10:00:00.000Z'
        sharingAccess:
          $ref: '#/components/schemas/EmployeeGroupSharingAccess'
        canWrite:
          type: boolean
          description: Whether you have permission to edit this group.
          title: Can edit
          example: true
      required:
        - id
        - name
        - type
        - categoryIds
        - employeeCount
        - integrationId
        - integrationUserGroupId
        - integrationUserGroupExternalType
        - createdByEmployeeId
        - createdAt
        - updatedAt
        - sharingAccess
        - canWrite
      title: Employee group
      description: >-
        Employee group in this company, its current employee count, and your
        permission to edit it.
      example:
        id: group-engineering
        name: Engineering
        type: MANUAL
        categoryIds:
          - 11111111-1111-4111-8111-111111111111
        employeeCount: 1
        integrationId: null
        integrationUserGroupId: null
        integrationUserGroupExternalType: null
        createdByEmployeeId: employee-avery
        createdAt: '2026-01-15T10:00:00.000Z'
        updatedAt: '2026-01-15T10:00:00.000Z'
        sharingAccess:
          companyAccess: read
          allManagersAccess: none
          employeeAccess:
            - employeeId: employee-avery
              access: write
          groupAccess: []
          subtreeAccess: []
        canWrite: true
    EmployeeGroupPagination:
      type: object
      properties:
        page:
          type: integer
          minimum: 1
          default: 1
          description: One-based page number. Defaults to 1.
          title: Page number
          example: 1
        pageSize:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
          description: Maximum results per page, from 1 to 100. Defaults to 50.
          title: Page size
          example: 50
        hasMore:
          type: boolean
          description: Whether there are more matching results after this page.
          title: Has another page
          example: false
        total:
          type: integer
          minimum: 0
          description: >-
            Total matching items, independent of pagination. The route
            determines the item type.
          title: Total matches
          example: 1
      required:
        - page
        - pageSize
        - hasMore
      title: Group pagination
      example:
        page: 1
        pageSize: 50
        hasMore: false
        total: 1
      description: Page position and optional total count.
    EmployeeGroupSharingAccess:
      type: object
      properties:
        companyAccess:
          type: string
          enum:
            - none
            - read
            - write
          description: Access for everyone in this company.
          title: Company access
          example: read
        allManagersAccess:
          type: string
          enum:
            - none
            - read
            - write
          description: Access for employees who manage others.
          title: All managers access
          example: read
        employeeAccess:
          type: array
          items:
            type: object
            properties:
              employeeId:
                type: string
                minLength: 1
                description: Employee ID in this company.
                title: Employee ID
                example: employee-avery
              access:
                type: string
                enum:
                  - none
                  - read
                  - write
                description: No access, read access, or read and edit access.
                title: Access level
                example: read
            required:
              - employeeId
              - access
          description: Access granted directly to employees.
          title: Employee access
          example:
            - employeeId: employee-avery
              access: write
        groupAccess:
          type: array
          items:
            type: object
            properties:
              groupId:
                type: string
                minLength: 1
                description: Employee group ID in this company.
                title: Group ID
                example: group-engineering
              access:
                type: string
                enum:
                  - none
                  - read
                  - write
                description: No access, read access, or read and edit access.
                title: Access level
                example: read
            required:
              - groupId
              - access
          description: Access granted to members of employee groups.
          title: Group access
          example: []
        subtreeAccess:
          type: array
          items:
            type: object
            properties:
              employeeId:
                type: string
                minLength: 1
                description: Employee ID in this company.
                title: Employee ID
                example: employee-avery
              access:
                type: string
                enum:
                  - none
                  - read
                  - write
                description: No access, read access, or read and edit access.
                title: Access level
                example: read
            required:
              - employeeId
              - access
          description: Access granted to employees in the specified reporting subtrees.
          title: Reporting subtree access
          example: []
      required:
        - companyAccess
        - allManagersAccess
        - employeeAccess
        - groupAccess
        - subtreeAccess
      title: Sharing access
      description: Who can read or edit this employee group.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use an API key or OAuth access token. Enter only the token in the
        authorization dialog; requests send it as `Authorization: Bearer
        <TOKEN>`.


        Create an API key in your workspace's **Settings → API keys**. Keys
        start with `wm_api_` and only work in the workspace where they were
        created. Read-only keys can read data; creating, updating, or deleting
        data requires a read-write key.


        ```http

        Authorization: Bearer wm_api_example

        ```


        OAuth access tokens are issued for connected Windmill applications.


        ```http

        Authorization: Bearer <OAUTH_ACCESS_TOKEN>

        ```


        Both token types use the authenticated user's workspace permissions.
        Each endpoint's permission requirements and the sharing settings of the
        requested items still apply.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.