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

> List CometChat messages with REST API using filters for users, groups, categories, types, timestamps, and threads.

# List Messages

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


## OpenAPI

````yaml get /messages
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:
  /messages:
    get:
      tags:
        - Messages
      summary: List Messages
      description: Fetches the messages list.
      operationId: list-all-messages
      parameters:
        - $ref: '#/components/parameters/onBehalfOf'
        - name: searchKey
          in: query
          description: Fetches messages that include the searchKey.
          schema:
            type: string
        - name: hideMessagesFromBlockedUsers
          in: query
          description: >-
            Fetches messages sent by users who are blocked by the requesting
            user.
          schema:
            type: boolean
        - name: hasAttachments
          in: query
          description: Fetches messages that include attachments.
          schema:
            type: boolean
        - name: attachmentTypes
          in: query
          description: >-
            Displays messages according to the type of attachment. Supported
            types include: image, video, audio, and file.
          schema:
            type: string
            enum:
              - image
              - video
              - audio
              - file
        - name: hasMentions
          in: query
          description: Fetches messages that include mentions.
          schema:
            type: boolean
        - name: hasLinks
          in: query
          description: Fetches messages that include links.
          schema:
            type: boolean
        - name: mentionedUids
          in: query
          description: Fetches messages that include the mentioned comma-separated UIDs.
          schema:
            type: boolean
        - name: hasReactions
          in: query
          description: Fetches messages that include reactions.
          schema:
            type: boolean
        - name: receiverType
          in: query
          description: Displays messages based on receiverType (user/group)
          schema:
            type: string
            enum:
              - user
              - group
        - name: affix
          in: query
          description: >-
            Determines whether to pull the messages either before or after any
            message id. Possible values are append(after) and prepend(before).
          schema:
            type: string
        - name: id
          in: query
          description: Retrieves all those messages after the passed id.
          schema:
            type: string
        - name: category
          in: query
          description: >-
            Filters messages by category. Possible values: message, action and
            custom.
          schema:
            type: string
            enum:
              - message
              - action
              - custom
        - name: type
          in: query
          description: Filters messages by type.
          schema:
            type: string
        - name: sender
          in: query
          description: >-
            Filters messages with sender. If onBehalfOf header is also set then
            the messages from their common conversations will be filtered.
          schema:
            type: string
        - name: senders
          in: query
          description: >-
            Filter messages by multiple sender UIDs. Accepts comma-separated UID
            values.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: mentionsWithBlockedInfo
          in: query
          description: >-
            For the mentioned users, provides blocked information with respect
            to the UID in onBehalfOf header.
          schema:
            type: boolean
        - name: mentionsWithTagInfo
          in: query
          description: Provides user tags for the mentioned users.
          schema:
            type: boolean
        - name: hideDeleted
          in: query
          description: Hides deleted messages from List.
          schema:
            type: boolean
        - name: onlyDeleted
          in: query
          description: Includes only deleted messages in List.
          schema:
            type: boolean
        - name: hideReplies
          in: query
          description: Shows only messages skipping the replies in the message thread.
          schema:
            type: boolean
        - name: count
          in: query
          description: Includes unread message count in List.
          schema:
            type: boolean
        - name: unread
          in: query
          description: >-
            Retrieves all the unread messages in a conversation. It must be used
            alongside count query parameter.
          schema:
            type: boolean
        - name: sentAt
          in: query
          description: Fetches the messages list after a particular sentAt timestamp.
          schema:
            type: integer
        - name: sentAt[from]
          in: query
          description: >-
            Filter by sentAt start timestamp (Unix timestamp). Filters messages
            sent on or after this timestamp. Can be used with sentAt[to] for a
            date range.
          schema:
            type: integer
            example: 1738368000
        - name: sentAt[to]
          in: query
          description: >-
            Filter by sentAt end timestamp (Unix timestamp). Filters messages
            sent on or before this timestamp. Can be used with sentAt[from] for
            a date range.
          schema:
            type: integer
            example: 1739059200
        - name: updatedAt[from]
          in: query
          description: >-
            Filter by updatedAt start timestamp (Unix timestamp). Filters
            messages updated on or after this timestamp. Only returns messages
            that have actually been updated (excludes messages 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 messages
            updated on or before this timestamp. Only returns messages that have
            actually been updated (excludes messages where updatedAt equals
            createdAt). Can be used with updatedAt[from] for a date range.
          schema:
            type: integer
            example: 1739059200
        - name: editedAt[from]
          in: query
          description: >-
            Filter by editedAt start timestamp (Unix timestamp). Filters
            messages edited on or after this timestamp. Can be used with
            editedAt[to] for a date range.
          schema:
            type: integer
            example: 1738368000
        - name: editedAt[to]
          in: query
          description: >-
            Filter by editedAt end timestamp (Unix timestamp). Filters messages
            edited on or before this timestamp. Can be used with editedAt[from]
            for a date range.
          schema:
            type: integer
            example: 1739059200
        - name: limit
          in: query
          description: >-
            The number of records to fetch. Minimum value: 1, Maximum value:
            1000
          schema:
            type: integer
            default: '10'
        - name: conversationId
          in: query
          description: Fetches all the messages belong to a particular conversation.
          schema:
            type: string
        - name: withTags
          in: query
          description: This will fetch messages along with the tags.
          schema:
            type: boolean
        - name: tags
          in: query
          description: This will fetch only those messages belonging to the mentioned tags.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: categories
          in: query
          description: Fetches messages based on multiple categories.
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: types
          in: query
          description: Fetches messages based on multiple types.
          schema:
            type: array
            items: {}
        - name: fromTimestamp
          in: query
          description: Fetches the messages from this timestamp.
          schema:
            type: integer
        - name: toTimestamp
          in: query
          description: >-
            Fetches the messages till this timestamp. It will be ignored if
            fromTimestamp is missing or empty.
          schema:
            type: integer
        - name: hideQuotedMessages
          in: query
          description: >-
            If set to true, the API response will exclude all quotedMessage
            nodes from the returned messages. This allows clients to fetch only
            the messages without any quoted messages.
          schema:
            type: boolean
      responses:
        '200':
          description: List Message
          content:
            application/json:
              schema:
                properties:
                  data:
                    type: array
                    items: {}
                  meta:
                    type: object
                type: object
              example:
                data:
                  - id: '1'
                    conversationId: superhero3_user_superhero5
                    sender: superhero3
                    receiverType: user
                    receiver: superhero5
                    category: message
                    type: text
                    data:
                      text: test     hello
                      entities:
                        sender:
                          entity:
                            uid: superhero3
                            name: Spiderman
                            role: default
                            avatar: >-
                              https://data-us.cometchat.io/assets/images/avatars/spiderman.png
                            status: offline
                            createdAt: 1638361550
                          entityType: user
                        receiver:
                          entity:
                            uid: superhero5
                            name: Cyclops
                            role: default
                            avatar: >-
                              https://data-us.cometchat.io/assets/images/avatars/cyclops.png
                            status: offline
                            createdAt: 1638361550
                            conversationId: superhero3_user_superhero5
                          entityType: user
                      metadata:
                        key1: val1
                    sentAt: 1638423490
                    updatedAt: 1638423490
                meta:
                  current:
                    limit: 100
                    count: 1
                  next:
                    affix: append
                    sentAt: 1638423490
                    id: '1'
      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

````