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

# Obtener Logs del Monitor

> Obtiene el historial de eventos del agente de IA. Permite consultar eventos recientes, filtrar por contacto especifico, o buscar por sesion/nombre de contacto.

El endpoint selecciona automaticamente la consulta segun los parametros:
- Si se envia `search`: busca por session_id o contact_name (busqueda profunda)
- Si se envia `contactId`: filtra eventos de un contacto especifico
- Si no se envia ninguno: retorna los eventos mas recientes

### Tipos de evento disponibles

| event_type | Descripcion |
|---|---|
| `msg_in` | Mensaje entrante del contacto |
| `msg_out` | Respuesta del agente |
| `model` | Proveedor y modelo de IA seleccionado |
| `tool_call` | Llamada a herramienta del LLM |
| `api_req` | Request HTTP a servicio externo |
| `api_res` | Response del servicio externo |
| `action` | Accion ejecutada (asignar agente, etiqueta, etapa, etc.) |
| `rag` | Busqueda en base de conocimiento |
| `tokens` | Consumo de tokens (input/output) |
| `error` | Error durante el procesamiento |
| `bot_off` | Bot apagado |
| `session_field` | Campo de sesion solicitado |

### Ejemplos de uso

**Ultimos 100 eventos:**
```bash
curl "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&limit=100" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Authorization: Bearer TOKEN"
```

**Buscar por telefono (session_id):**
```bash
curl "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&search=51932114990&from=2026-03-01 00:00:00&limit=200" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Authorization: Bearer TOKEN"
```

**Buscar por nombre de contacto:**
```bash
curl "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&search=Maria&from=2026-03-01 00:00:00&limit=200" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Authorization: Bearer TOKEN"
```

**Filtrar por contacto especifico:**
```bash
curl "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&contactId=CONTACT_ID&from=2026-03-01 00:00:00&limit=50" \
  -H "x-workspace-id: WORKSPACE_ID" \
  -H "Authorization: Bearer TOKEN"
```



## OpenAPI

````yaml GET /api/agent/logs
openapi: 3.1.0
info:
  title: Plazbot
  description: >-
    Documentacion completa de la API de Plazbot. Incluye todos los servicios
    para gestion de contactos, conversaciones, mensajes, oportunidades, tareas,
    plantillas, agentes de IA, usuarios y workspaces.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.plazbot.com
    description: Servidor de produccion de Plazbot
security:
  - bearerAuth: []
tags:
  - name: automation
    description: Servicios de automatizacion y nodos de IA
  - name: agent
    description: Servicios para gestion de Agentes de Inteligencia Artificial
  - name: contact
    description: Servicios para gestion de contactos del workspace
  - name: conversation
    description: Servicios para gestion de conversaciones y campanas
  - name: message
    description: Servicios para envio y gestion de mensajes
  - name: opportunity
    description: Servicios para gestion de oportunidades de negocio
  - name: task
    description: Servicios para gestion de tareas
  - name: template
    description: Servicios para gestion de plantillas de WhatsApp
  - name: user
    description: Servicios para gestion de usuarios y autenticacion
  - name: workspace
    description: Servicios para gestion de workspaces
paths:
  /api/agent/logs:
    get:
      tags:
        - agent
      summary: Obtener Logs del Monitor
      description: >-
        Obtiene el historial de eventos del agente de IA. Permite consultar
        eventos recientes, filtrar por contacto especifico, o buscar por
        sesion/nombre de contacto.


        El endpoint selecciona automaticamente la consulta segun los parametros:

        - Si se envia `search`: busca por session_id o contact_name (busqueda
        profunda)

        - Si se envia `contactId`: filtra eventos de un contacto especifico

        - Si no se envia ninguno: retorna los eventos mas recientes


        ### Tipos de evento disponibles


        | event_type | Descripcion |

        |---|---|

        | `msg_in` | Mensaje entrante del contacto |

        | `msg_out` | Respuesta del agente |

        | `model` | Proveedor y modelo de IA seleccionado |

        | `tool_call` | Llamada a herramienta del LLM |

        | `api_req` | Request HTTP a servicio externo |

        | `api_res` | Response del servicio externo |

        | `action` | Accion ejecutada (asignar agente, etiqueta, etapa, etc.) |

        | `rag` | Busqueda en base de conocimiento |

        | `tokens` | Consumo de tokens (input/output) |

        | `error` | Error durante el procesamiento |

        | `bot_off` | Bot apagado |

        | `session_field` | Campo de sesion solicitado |


        ### Ejemplos de uso


        **Ultimos 100 eventos:**

        ```bash

        curl "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&limit=100"
        \
          -H "x-workspace-id: WORKSPACE_ID" \
          -H "Authorization: Bearer TOKEN"
        ```


        **Buscar por telefono (session_id):**

        ```bash

        curl
        "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&search=51932114990&from=2026-03-01
        00:00:00&limit=200" \
          -H "x-workspace-id: WORKSPACE_ID" \
          -H "Authorization: Bearer TOKEN"
        ```


        **Buscar por nombre de contacto:**

        ```bash

        curl
        "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&search=Maria&from=2026-03-01
        00:00:00&limit=200" \
          -H "x-workspace-id: WORKSPACE_ID" \
          -H "Authorization: Bearer TOKEN"
        ```


        **Filtrar por contacto especifico:**

        ```bash

        curl
        "https://api.plazbot.com/api/agent/logs?agentId=AGENT_ID&contactId=CONTACT_ID&from=2026-03-01
        00:00:00&limit=50" \
          -H "x-workspace-id: WORKSPACE_ID" \
          -H "Authorization: Bearer TOKEN"
        ```
      operationId: getAgentMonitorLogs
      parameters:
        - name: x-workspace-id
          in: header
          description: Identificador del workspace
          required: true
          schema:
            type: string
        - name: agentId
          in: query
          description: ID del Agente de IA
          required: true
          schema:
            type: string
        - name: contactId
          in: query
          description: >-
            ID del contacto para filtrar eventos de un contacto especifico. No
            se puede combinar con `search`.
          required: false
          schema:
            type: string
        - name: search
          in: query
          description: >-
            Texto para buscar en session_id (numero de telefono) o contact_name.
            Coincidencia parcial, case insensitive. No se puede combinar con
            `contactId`.
          required: false
          schema:
            type: string
          examples:
            phone:
              summary: Buscar por telefono
              value: '51932114990'
            name:
              summary: Buscar por nombre
              value: Maria
        - name: from
          in: query
          description: >-
            Fecha desde la cual obtener eventos. Formato: `YYYY-MM-DD HH:MM:SS`.
            Si no se especifica, retorna los mas recientes.
          required: false
          schema:
            type: string
            format: date-time
          example: '2026-03-01 00:00:00'
        - name: limit
          in: query
          description: Cantidad maxima de eventos a retornar
          required: false
          schema:
            type: integer
            default: 100
            minimum: 1
            maximum: 500
      responses:
        '200':
          description: Lista de eventos del agente obtenida exitosamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Indica si la operacion fue exitosa
                    example: true
                  data:
                    type: array
                    description: >-
                      Array de eventos del agente ordenados por timestamp
                      descendente
                    items:
                      $ref: '#/components/schemas/AgentLogEvent'
        '400':
          description: Solicitud incorrecta - agentId es requerido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No autorizado - Token Bearer requerido o invalido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Servicio no disponible - El servicio de logging no esta configurado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    AgentLogEvent:
      type: object
      description: >-
        Evento del monitor del agente de IA. Cada interaccion del agente genera
        multiples eventos que registran el flujo completo de procesamiento.
      properties:
        timestamp:
          type: string
          format: date-time
          description: Fecha y hora UTC del evento
          example: '2026-03-14 15:30:01'
        workspace_id:
          type: string
          description: ID del workspace
        agent_id:
          type: string
          description: ID del agente de IA
        contact_id:
          type: string
          description: ID del contacto (vacio si no aplica)
        contact_name:
          type: string
          description: Nombre del contacto para display
          example: Maria Garcia
        session_id:
          type: string
          description: >-
            ID de sesion. En WhatsApp es el numero de telefono, en Messenger el
            Facebook User ID, en Instagram el IG User ID, en Telegram el TG User
            ID.
          example: '51932114990'
        event_type:
          type: string
          description: Tipo de evento
          enum:
            - msg_in
            - msg_out
            - model
            - tool_call
            - api_req
            - api_res
            - action
            - rag
            - tokens
            - error
            - bot_off
            - session_field
          example: msg_in
        event_title:
          type: string
          description: >-
            Titulo corto del evento para mostrar en el monitor. Ejemplos:
            mensaje del contacto, nombre de herramienta, URL del servicio,
            accion ejecutada.
          example: Hola, quiero informacion de precios
        event_data:
          type: string
          description: >-
            JSON string con datos especificos del evento. El contenido varia
            segun el event_type. Para msg_in/msg_out contiene el mensaje
            completo, para tool_call los argumentos, para api_req el body del
            request, para action los detalles de la accion, para tokens el
            consumo.
          example: >-
            {"message":"Hola, quiero informacion de
            precios","platform":"whatsapp"}
        duration_ms:
          type: integer
          description: Duracion en milisegundos (relevante para api_res y tool_call)
          example: 340
        level:
          type: string
          description: Nivel de severidad del evento
          enum:
            - info
            - warning
            - error
          example: info
    ErrorResponse:
      type: object
      description: Respuesta de error estandar de la API
      properties:
        success:
          type: boolean
          description: Siempre false en errores
        code:
          type: integer
          description: Codigo HTTP del error
        errorCode:
          type:
            - string
            - 'null'
          description: Codigo de error especifico
        message:
          type: string
          description: Mensaje descriptivo del error
      required:
        - success
        - code
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Token de autenticacion Bearer. Obtenga el token usando el endpoint
        /api/user/login

````