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

# Query Agent Analytics

> Query various metrics about a agent, such as the number of conversations, the number of users, and the number of messages



## OpenAPI

````yaml post /agents/{agentId}/analytics/query
openapi: 3.0.1
info:
  title: ChatDash API Documentation
  description: API Documentation for the ChatDash Server
  version: 2.0.0
servers:
  - url: https://api.chat-dash.com/v1/public
security: []
paths:
  /agents/{agentId}/analytics/query:
    post:
      tags:
        - Analytics
      summary: Query Agent Analytics
      description: >-
        Query various metrics about a agent, such as the number of
        conversations, the number of users, and the number of messages
      parameters:
        - name: Authorization
          in: header
          required: true
          description: >-
            All requests to the ChatDash API must be validated with the agency
            API Key found on your agency profile
          schema:
            type: string
        - name: agentId
          in: path
          required: true
          description: The ID of the agent
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: object
                  properties:
                    metrics:
                      type: array
                      items:
                        type: string
                        description: The metrics to query
                        enum:
                          - conversations
                          - conversationByCountry
                          - uniqueIps
                          - totalCallDuration
                          - totalCost
                          - averageCost
                          - topMisunderstoodMessages
                          - topTopics
                          - endedReason
                          - interactions
                          - incomingTextMessages
                          - tokens
                          - topIntents
                          - understoodMessages
                          - averageInteractions
                    filter:
                      type: object
                      properties:
                        startTime:
                          type: string
                          description: >-
                            UTC Timestamp in ISO 8601 format
                            (YYYY-MM-DDTHH:mm:ss.sssZ)
                        endTime:
                          type: string
                          description: >-
                            UTC Timestamp in ISO 8601 format
                            (YYYY-MM-DDTHH:mm:ss.sssZ)
                        utcOffset:
                          type: string
                          description: >-
                            The UTC offset for where the request is made from in
                            the format UTC±[hh], e.g., "UTC-4"
                  required:
                    - metrics
                    - filter
              required:
                - query
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  conversations:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: integer
                        description: The number of conversations by day
                      total:
                        type: integer
                        description: The total number of conversations
                  conversationsByCountry:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Country identifier
                        value:
                          type: integer
                          description: Number of conversations for the country
                  uniqueIps:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: integer
                        description: The number of unique IPs by day
                      total:
                        type: integer
                        description: The total number of unique IPs
                  totalCallDuration:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: number
                        description: The total call duration by day
                      total:
                        type: number
                        description: The overall total call duration
                  totalCost:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: number
                        description: The total cost by day
                      total:
                        type: number
                        description: The overall total cost
                      currency:
                        type: string
                        description: The currency format used
                  averageCost:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: number
                        description: The average cost by day
                      average:
                        type: number
                        description: The overall average cost
                      currency:
                        type: string
                        description: The currency format used
                  endedReason:
                    type: array
                    items:
                      type: object
                      properties:
                        reason:
                          type: string
                          description: The reason for ending the conversation
                        count:
                          type: integer
                          description: The number of conversations ended for this reason
                  topMisunderstoodMessages:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Identifier for the misunderstood message
                        label:
                          type: string
                          description: Label of the misunderstood message
                        count:
                          type: integer
                          description: Number of occurrences
                    maxItems: 5
                  topTopics:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: Identifier for the topic
                        label:
                          type: string
                          description: Label of the topic
                        count:
                          type: integer
                          description: Number of occurrences
                    maxItems: 5
                  interactions:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: integer
                        description: The number of interactions by day
                      total:
                        type: integer
                        description: The total number of interactions
                  incomingTextMessages:
                    type: object
                    properties:
                      counts:
                        type: array
                        items:
                          type: integer
                        description: The number of incoming text messages by day
                      total:
                        type: integer
                        description: The total number of incoming text messages
                  tokens:
                    type: array
                    items:
                      type: object
                      properties:
                        model:
                          type: string
                          description: The model name
                        count:
                          type: integer
                          description: The token count for this model
                  topIntents:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The intent name
                        count:
                          type: integer
                          description: The number of occurrences of this intent
                  understoodMessages:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: The total number of messages
                      understood:
                        type: integer
                        description: The number of understood messages
                      missed:
                        type: integer
                        description: The number of not understood messages
                  averageInteractions:
                    type: integer
                    description: The average number of interactions per conversation
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: An unexpected error occurred

````