> ## Documentation Index
> Fetch the complete documentation index at: https://cometchat-22654f5b-docs-restapi-chat-api-eng-37141.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Lists the groups.

# List

For the complete error reference, see [Error Guide](/articles/error-guide).


## OpenAPI

````yaml get /groups
openapi: 3.0.0
info:
  title: Chat APIs
  description: Manage messages, users, groups for a particular app using our Chat API.
  version: '3.0'
servers:
  - url: https://{appId}.api-{region}.cometchat.io/v3
    variables:
      appId:
        default: appId
        description: (Required) App ID
      region:
        enum:
          - us
          - eu
          - in
        default: us
        description: Select Region
security: []
tags:
  - name: API Keys
    description: The API keys are used to authorise the APIs
  - name: Roles
    description: The roles are used to give user access rights
  - name: Users
    description: The REST collection for users.
  - name: Auth Tokens
    description: The auth tokens are used to login end users using client SDKs.
  - name: Blocked Users
    description: The REST collections for blocked users.
  - name: Friends
    description: List,add and remove friends by passing UID in path variables
  - name: Groups
    description: The REST collections for groups.
  - name: Banned Users
    description: Ban and Unban user by passing other UID in path variables.
  - name: Group Members
    description: The REST collections for group members.
  - name: Messages
    description: The REST collections for messages.
  - name: Conversations
    description: The REST collections for conversations.
  - name: Restrict Features
    description: Allows Restricting Features
  - name: Metrics
    description: Allows accessing Data Metrics
  - name: Triggers
    description: Allows adding triggers to a webhook.
  - name: Webhooks
    description: Allows accessing Webhooks.
  - name: Notifications
    description: Allows configuring Notifications core.
  - name: Moderation
    description: The REST collections for Moderations.
paths:
  /groups:
    get:
      tags:
        - Groups
      summary: List
      description: Lists the groups.
      operationId: list-groups
      parameters:
        - $ref: '#/components/parameters/onBehalfOf'
        - name: searchKey
          in: query
          description: >-
            Searches for given keyword in group's list (either GUID, name or
            email).
          schema:
            type: string
        - name: searchIn
          in: query
          description: Searches for specified keyword in name,GUID or both.
          schema:
            type: array
            items:
              type: string
        - name: sortBy
          in: query
          description: >-
            Sorts the group list by either Name,Guid or Created at . Available
            values: name, guid, createdAt
          schema:
            type: string
            enum:
              - name
              - guid
              - createdAt
        - name: sortOrder
          in: query
          description: >-
            Sorts the group list in ascending or descending order. Available
            values: asc, desc
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: perPage
          in: query
          description: >-
            Number of groups to be fetched in a request. The default value is
            100 and the maximum value is 1000.
          schema:
            type: integer
            default: '100'
        - name: affix
          in: query
          description: >-
            Determines whether to fetch the groups either before or after
            createdAt/updatedAt timestamp. Possible values are append(after) and
            prepend(before).
          schema:
            type: string
            enum:
              - append
              - prepend
        - name: updatedAt
          in: query
          description: Fetches the groups list after a particular updatedAt timestamp.
          schema:
            type: integer
        - name: withTags
          in: query
          description: Includes those groups that have tags.
          schema:
            type: boolean
        - name: tags
          in: query
          description: Fetches only those groups that have these tags.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: type
          in: query
          description: Fetches groups based on group type(public, protected, password).
          schema:
            type: string
            enum:
              - public
              - private
              - protected
        - name: types
          in: query
          description: Fetches groups based on multiple types.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: page
          in: query
          description: Page number.
          schema:
            type: integer
        - name: hasJoined
          in: query
          description: >-
            Fetches all the joined groups of a user. This will work only with
            onBehalfOf parameter in header. It accepts only true as a value,
            setting it as false simply removes this filter.
          schema:
            type: boolean
        - name: guid
          in: query
          description: Filter groups by a specific GUID. Accepts a single GUID value.
          schema:
            type: string
        - name: guids
          in: query
          description: >-
            Filter groups by multiple GUIDs. Accepts comma-separated GUID
            values.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: createdAt[from]
          in: query
          description: >-
            Filter by createdAt start timestamp (Unix timestamp). Filters groups
            created on or after this timestamp. Can be used with createdAt[to]
            for a date range.
          schema:
            type: integer
            example: 1738368000
        - name: createdAt[to]
          in: query
          description: >-
            Filter by createdAt end timestamp (Unix timestamp). Filters groups
            created on or before this timestamp. Can be used with
            createdAt[from] for a date range.
          schema:
            type: integer
            example: 1739059200
        - name: updatedAt[from]
          in: query
          description: >-
            Filter by updatedAt start timestamp (Unix timestamp). Filters groups
            updated on or after this timestamp. Only returns groups that have
            actually been updated (excludes groups where updatedAt equals
            createdAt). Can be used with updatedAt[to] for a date range.
          schema:
            type: integer
            example: 1738368000
        - name: updatedAt[to]
          in: query
          description: >-
            Filter by updatedAt end timestamp (Unix timestamp). Filters groups
            updated on or before this timestamp. Only returns groups that have
            actually been updated (excludes groups where updatedAt equals
            createdAt). Can be used with updatedAt[from] for a date range.
          schema:
            type: integer
            example: 1739059200
        - name: membersCount[gte]
          in: query
          description: >-
            Filter groups by members count using comparison operators. Supported
            operators: gt (greater than), gte (greater than or equal), lt (less
            than), lte (less than or equal), eq (equal). Example:
            membersCount[gte]=2&membersCount[lte]=10 for a range.
          schema:
            type: integer
            example: 2
        - name: membersCount[lte]
          in: query
          description: Filter groups with members count less than or equal to this value.
          schema:
            type: integer
            example: 10
        - name: membersCount[eq]
          in: query
          description: Filter groups with members count equal to this value.
          schema:
            type: integer
            example: 5
      responses:
        '200':
          description: A list of groups
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                  cursor:
                    properties:
                      updatedAt:
                        type: integer
                      affix:
                        type: string
                    type: object
                type: object
              example:
                data:
                  - guid: project-group
                    name: Project Group
                    description: project related discussions between members
                    icon: http://placehold.it/120x120&text=image1
                    type: public
                    scope: admin
                    membersCount: 1
                    joinedAt: 1638440784
                    conversationId: group_project-group
                    hasJoined: true
                    createdAt: 1638440784
                    owner: superhero4
                    tags:
                      - friends
                      - project
                  - guid: project-group-2
                    name: Project Group 2
                    description: project related discussions between members
                    icon: http://placehold.it/120x120&text=image1
                    type: public
                    scope: admin
                    membersCount: 1
                    joinedAt: 1638440784
                    conversationId: group_project-group
                    hasJoined: true
                    createdAt: 1638440784
                    owner: superhero4
                    tags:
                      - friends
                      - project
                meta:
                  pagination:
                    total: 0
                    count: 5
                    per_page: 100
                    current_page: 1
                    total_pages: 1
                  cursor:
                    updatedAt: 1638354799
                    affix: prepend
      security:
        - apiKey: []
components:
  parameters:
    onBehalfOf:
      name: onBehalfOf
      in: header
      description: UID of the user on whose behalf the action is performed.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      description: API Key with fullAccess scope(i.e. Rest API Key from the Dashboard).
      name: apikey
      in: header

````