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

# Buscar mensagens

> Pesquisa as mensagens armazenadas, opcionalmente filtradas por uma cláusula `where` e limitadas por `limit`.



## OpenAPI

````yaml openapi.evolution-v2.pt.json POST /chat/findMessages/{instance}
openapi: 3.1.0
info:
  title: Evolution V2 Layer
  version: 1.0.0
  description: >-
    Camada de API do Pilot Status — Evolution V2. Base URL
    `https://pilotstatus.com.br/api/layer/evolution-v2`. Autentique com o header
    `apikey` (sua chave `ps_` do Pilot Status). Endpoints de instância/sessão
    NÃO estão disponíveis na camada.
servers:
  - url: https://pilotstatus.com.br/api/layer/evolution-v2
security:
  - apiKey: []
tags:
  - name: Chamada e Business
  - name: Chat
  - name: Grupo
  - name: Etiqueta (Label)
  - name: Mensagem
  - name: Perfil
  - name: Configurações e Proxy
  - name: Armazenamento (S3)
  - name: Template
paths:
  /chat/findMessages/{instance}:
    post:
      tags:
        - Chat
      summary: Buscar mensagens
      description: >-
        Pesquisa as mensagens armazenadas, opcionalmente filtradas por uma
        cláusula `where` e limitadas por `limit`.
      operationId: post__chat_findMessages_instance
      parameters:
        - name: instance
          in: path
          required: true
          schema:
            type: string
          description: O nome de exibição do número no painel do Pilot Status.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                where:
                  type: object
                  description: >-
                    Filtro com `_id`, `key` (`id`, `remoteJid`, `fromMe`) ou
                    `message`.
                  example:
                    key:
                      remoteJid: 5511999999999@s.whatsapp.net
                limit:
                  type: integer
                  description: Número máximo de mensagens a serem retornadas.
                  example: 20
      responses:
        '200':
          description: Sucesso — corpo de resposta nativo do provedor.
          content:
            application/json:
              schema:
                type: object
                description: Paginated stored messages for the instance.
                properties:
                  messages:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total number of matching messages.
                      pages:
                        type: integer
                        description: Total number of pages given the page size.
                      currentPage:
                        type: integer
                        description: Current page number (1-based).
                      records:
                        type: array
                        description: >-
                          Messages on this page, ordered by messageTimestamp
                          desc.
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: Message record id (cuid).
                            key:
                              type: object
                              description: Baileys message key.
                              properties:
                                remoteJid:
                                  type: string
                                fromMe:
                                  type: boolean
                                id:
                                  type: string
                                participant:
                                  type: string
                            pushName:
                              type:
                                - string
                                - 'null'
                              description: Sender push name.
                            messageType:
                              type: string
                              description: Message type, e.g. conversation, imageMessage.
                            message:
                              type: object
                              description: Raw Baileys message content object.
                            messageTimestamp:
                              type: integer
                              description: Unix timestamp (seconds).
                            instanceId:
                              type: string
                              description: Owning instance id.
                            source:
                              type: string
                              description: Originating device, e.g. android, ios, web.
                            contextInfo:
                              type:
                                - object
                                - 'null'
                              description: Context info (quotes, mentions), when present.
                            MessageUpdate:
                              type: array
                              description: Latest status updates for the message.
                              items:
                                type: object
                                properties:
                                  status:
                                    type: string
                                    description: >-
                                      Delivery status, e.g. DELIVERY_ACK, READ,
                                      PENDING.
                    required:
                      - total
                      - pages
                      - currentPage
                      - records
                required:
                  - messages
              example:
                messages:
                  total: 128
                  pages: 3
                  currentPage: 1
                  records:
                    - id: clzmsg0012233445566778899
                      key:
                        remoteJid: 5511999999999@s.whatsapp.net
                        fromMe: false
                        id: 3EB0C767D26A1D8A0F1B
                      pushName: Maria Silva
                      messageType: conversation
                      message:
                        conversation: Oi, tudo bem?
                      messageTimestamp: 1720544400
                      instanceId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                      source: android
                      contextInfo: null
                      MessageUpdate:
                        - status: READ
        default:
          description: Erro — erro do provedor ou da camada.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                  error:
                    type: string
                  message:
                    type: string
                  response:
                    type: object
              example:
                status: 400
                error: Bad Request
                message: Invalid payload
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: >-
        Your Pilot Status API key (ps_...). Evolution GO also accepts
        `Authorization: Bearer <key>`.

````