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

# Call Figures by Agent

> Returns all-time call figures for up to 30 agents in one request, in the order you asked (each agent once, duplicates removed). Each figure matches the agent's overview over all time. Agents with no calls get zeros and `null`s.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/agent-analytics/overview/by-agent
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v1/agent-analytics/overview/by-agent:
    get:
      summary: Get call figures for several agents
      description: >-
        Returns all-time call figures for up to 30 agents in one request, in the
        order you asked (each agent once, duplicates removed). Each figure
        matches the agent's overview over all time. Agents with no calls get
        zeros and `null`s.
      parameters:
        - in: query
          name: agentIds
          required: true
          style: form
          explode: true
          description: >-
            Agent IDs, 1 to 30. Repeat the parameter (`agentIds=a&agentIds=b`)
            or send a comma-separated list.
          schema:
            type: array
            minItems: 1
            maxItems: 30
            items:
              type: string
              format: uuid
            example:
              - 48f7656f-098b-4c43-b165-7cfd2cc8ac30
              - 6a1d7c52-93b0-4e1f-a7c4-2d8e5f9b0c31
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AnalyticsByAgentStats'
                    example:
                      - voiceAgentId: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
                        callStats:
                          total: 523
                          live: 2
                          averageDurationSeconds: 11.08
                          transferredToPersonPercent: 4.5
                      - voiceAgentId: 6a1d7c52-93b0-4e1f-a7c4-2d8e5f9b0c31
                        callStats:
                          total: 0
                          live: 0
                          averageDurationSeconds: null
                          transferredToPersonPercent: null
        '400':
          description: Missing `agentIds`, more than 30, or an ID that is not a UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: Your API key or role does not have the `statistics:read` permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    AnalyticsByAgentStats:
      type: object
      properties:
        voiceAgentId:
          type: string
          format: uuid
          example: 48f7656f-098b-4c43-b165-7cfd2cc8ac30
        callStats:
          type: object
          properties:
            total:
              type: integer
              description: All the agent's calls, all time, any status.
              example: 523
            live:
              type: integer
              description: Calls in progress that started in the last 10 minutes.
              example: 2
            averageDurationSeconds:
              type: number
              nullable: true
              description: >-
                Average length of finished calls, in seconds. `null` when the
                agent has no calls.
              example: 11.08
            transferredToPersonPercent:
              type: number
              nullable: true
              description: >-
                Percentage (0-100) of analysed finished calls handed to a
                person. `null` when the agent has no calls.
              example: 4.5
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.