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

# Get call stats

> Returns call volume, outcomes, answer rate and connected duration for a time range, grouped by day, hour, number or outcome, with an hour-of-week heatmap. Filters match the call records endpoints. Without `since` and `until` the range is the last 7 days. Day and hour groups use the requested `timezone` and include empty buckets.

Requires `sessions:read`. Project tokens only access resources in their own project.



## OpenAPI

````yaml api-reference/features/communicate.json GET /platform/calls/stats
openapi: 3.0.3
info:
  title: Communicate API methods
  version: 1.0.0
  description: >-
    Task-focused communicate methods across supported Polymorfa connection
    types.
servers: []
security: []
paths:
  /platform/calls/stats:
    get:
      tags:
        - Calls
      summary: Get call stats
      description: >-
        Returns call volume, outcomes, answer rate and connected duration for a
        time range, grouped by day, hour, number or outcome, with an
        hour-of-week heatmap. Filters match the call records endpoints. Without
        `since` and `until` the range is the last 7 days. Day and hour groups
        use the requested `timezone` and include empty buckets.


        Requires `sessions:read`. Project tokens only access resources in their
        own project.
      operationId: managementGetCallStats
      parameters:
        - name: projectId
          in: query
          required: false
          description: Project to read. Omit to total every project in the organization.
          schema:
            type: string
        - name: sessionId
          in: query
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 128
            description: Session name of one number.
          description: |-
            Identifier of the connected Polymorfa session.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | String length | `1` through `128` characters |
        - schema:
            type: string
            enum:
              - inbound
              - outbound
          required: false
          name: direction
          in: query
          description: |-
            Specifies direction for this query parameter.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `inbound` | Inbound. |
            | `outbound` | Outbound. |
        - name: upstream
          in: query
          required: false
          schema:
            type: string
            enum:
              - linked_device
              - cloud_api
            description: How the number connects to WhatsApp.
          description: |-
            Specifies upstream for this query parameter.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `linked_device` | Linked device. |
            | `cloud_api` | Cloud api. |
        - name: outcome
          in: query
          required: false
          schema:
            type: string
            enum:
              - answered
              - missed
              - declined
              - failed
              - in_progress
            description: >-
              How the call went. `answered`: media connected, including answered
              calls still in progress. `declined`: declined by a participant or
              the other party, or the line was busy. `missed`: nobody answered
              before ringing stopped or the caller hung up. `failed`: ended
              before it connected for any other reason, such as a connection or
              capacity failure. `in_progress`: still ringing.
          description: |-
            Specifies outcome for this query parameter.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `answered` | Answered. |
            | `missed` | Missed. |
            | `declined` | Declined. |
            | `failed` | Failed. |
            | `in_progress` | In progress. |
        - name: since
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: Include calls that started at or after this time.
          description: |-
            Specifies since for this query parameter.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        - name: until
          in: query
          required: false
          schema:
            type: string
            format: date-time
            description: Include calls that started before this time.
          description: |-
            Specifies until for this query parameter.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        - name: groupBy
          in: query
          required: false
          schema:
            type: string
            enum:
              - day
              - hour
              - session
              - outcome
            default: day
            description: >-
              `day` and `hour` return one group per bucket in `timezone`,
              covering at most 366 and 31 days. `session` returns one group per
              number, most calls first, up to 500. `outcome` returns one group
              per outcome.
          description: |-
            Specifies group by for this query parameter.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `day` | Day. |
            | `hour` | Hour. |
            | `session` | Session. |
            | `outcome` | Outcome. |
        - name: timezone
          in: query
          required: false
          schema:
            type: string
            default: UTC
            maxLength: 64
            example: Europe/Lisbon
            description: >-
              IANA time zone name for day and hour buckets and the heatmap, such
              as `UTC`, `CET` or `Europe/Lisbon`; case does not matter and the
              response carries the canonical name. UTC offsets and POSIX strings
              such as `UTC+3` are not accepted.
          description: |-
            Specifies timezone for this query parameter.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | String length | At most `64` characters |
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Stable request correlation identifier.
            Polymorfa-Version:
              schema:
                type: string
              description: API version applied to this response.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  data:
                    allOf:
                      - $ref: '#/components/schemas/management__CallStats'
                    description: Structured data carried by this object.
                required:
                  - data
        '400':
          $ref: '#/components/responses/management__BadRequest'
        '401':
          $ref: '#/components/responses/management__Unauthorized'
        '403':
          $ref: '#/components/responses/management__Forbidden'
        '503':
          $ref: '#/components/responses/management__CallStatsTooSlow'
      security:
        - management__ApiKeyAuth: []
      servers:
        - url: https://api.polymorfa.com
components:
  schemas:
    management__CallStats:
      type: object
      additionalProperties: false
      properties:
        since:
          type: string
          format: date-time
          description: |-
            Specifies since for this management call stat.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        until:
          type: string
          format: date-time
          description: |-
            Specifies until for this management call stat.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `date-time` |
        timezone:
          type: string
          description: Specifies timezone for this management call stat.
        groupBy:
          type: string
          enum:
            - day
            - hour
            - session
            - outcome
          description: |-
            Specifies group by for this management call stat.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `day` | Day. |
            | `hour` | Hour. |
            | `session` | Session. |
            | `outcome` | Outcome. |
        totals:
          allOf:
            - $ref: '#/components/schemas/management__CallStatsMetrics'
          description: Specifies totals for this management call stat.
        groups:
          type: array
          items:
            $ref: '#/components/schemas/management__CallStatsGroup'
          description: Groups associated with this management call stat.
        groupsTruncated:
          type: boolean
          description: >-
            True when a `session` grouping left out numbers beyond the first
            500. Totals still count every call.
        heatmap:
          type: array
          minItems: 168
          maxItems: 168
          items:
            $ref: '#/components/schemas/management__CallStatsHeatmapCell'
          description: >-
            Calls by day of week and hour, Monday 00:00 first. Every cell is
            present.


            <!-- polymorfa-input-table -->

            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Array size | `168` through `168` items |
      required:
        - since
        - until
        - timezone
        - groupBy
        - totals
        - groups
        - groupsTruncated
        - heatmap
    management__CallStatsMetrics:
      type: object
      additionalProperties: false
      properties:
        calls:
          type: integer
          minimum: 0
          description: |-
            Calls that started in the range.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        answered:
          type: integer
          minimum: 0
          description: |-
            Specifies answered for this management call stats metric.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        missed:
          type: integer
          minimum: 0
          description: |-
            Specifies missed for this management call stats metric.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        declined:
          type: integer
          minimum: 0
          description: |-
            Specifies declined for this management call stats metric.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        failed:
          type: integer
          minimum: 0
          description: |-
            Specifies failed for this management call stats metric.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        inProgress:
          type: integer
          minimum: 0
          description: |-
            Calls still ringing.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        answerRate:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          description: >-
            `answered` divided by calls that are no longer ringing, rounded to
            four decimals. Null when there are none.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `number`; Numeric value: `0` through `1`
            (inclusive) |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` through `1` (inclusive) |
        totalDurationSeconds:
          type: integer
          minimum: 0
          description: |-
            Connected seconds of answered calls.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        averageDurationSeconds:
          type: number
          minimum: 0
          nullable: true
          description: >-
            Mean connected seconds of answered calls that have ended, rounded to
            one decimal. Null when there are none.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `number`; Numeric value: `0` or greater |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` or greater |
      required:
        - calls
        - answered
        - missed
        - declined
        - failed
        - inProgress
        - answerRate
        - totalDurationSeconds
        - averageDurationSeconds
    management__CallStatsGroup:
      type: object
      additionalProperties: false
      properties:
        key:
          type: string
          description: >-
            Local date (`2026-09-18`) for `day`, local hour (`2026-09-18T14:00`)
            for `hour`, session name for `session`, or outcome for `outcome`.
        start:
          type: string
          format: date-time
          nullable: true
          description: >-
            Start of the day or hour bucket. Null for `session` and `outcome`
            groups.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `string`; Format: `date-time` |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Format | `date-time` |
        calls:
          type: integer
          minimum: 0
          description: |-
            Calls that started in the range.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        answered:
          type: integer
          minimum: 0
          description: |-
            Specifies answered for this management call stats group.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        missed:
          type: integer
          minimum: 0
          description: |-
            Specifies missed for this management call stats group.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        declined:
          type: integer
          minimum: 0
          description: |-
            Specifies declined for this management call stats group.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        failed:
          type: integer
          minimum: 0
          description: |-
            Specifies failed for this management call stats group.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        inProgress:
          type: integer
          minimum: 0
          description: |-
            Calls still ringing.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        answerRate:
          type: number
          minimum: 0
          maximum: 1
          nullable: true
          description: >-
            `answered` divided by calls that are no longer ringing, rounded to
            four decimals. Null when there are none.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `number`; Numeric value: `0` through `1`
            (inclusive) |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` through `1` (inclusive) |
        totalDurationSeconds:
          type: integer
          minimum: 0
          description: |-
            Connected seconds of answered calls.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        averageDurationSeconds:
          type: number
          minimum: 0
          nullable: true
          description: >-
            Mean connected seconds of answered calls that have ended, rounded to
            one decimal. Null when there are none.


            <!-- polymorfa-input-table -->

            **Accepted alternatives**

            | Alternative | Accepted input |

            | --- | --- |

            | Alternative 1 | Type: `number`; Numeric value: `0` or greater |

            | Alternative 2 | `null` |


            **Value constraints**

            | Constraint | Accepted input |

            | --- | --- |

            | Numeric value | `0` or greater |
      required:
        - key
        - start
        - calls
        - answered
        - missed
        - declined
        - failed
        - inProgress
        - answerRate
        - totalDurationSeconds
        - averageDurationSeconds
    management__CallStatsHeatmapCell:
      type: object
      additionalProperties: false
      properties:
        dayOfWeek:
          type: integer
          minimum: 1
          maximum: 7
          description: |-
            ISO day of week in `timezone`: 1 is Monday, 7 is Sunday.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `1` through `7` (inclusive) |
        hour:
          type: integer
          minimum: 0
          maximum: 23
          description: |-
            Specifies hour for this management call stats heatmap cell.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` through `23` (inclusive) |
        calls:
          type: integer
          minimum: 0
          description: |-
            Specifies calls for this management call stats heatmap cell.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
        answered:
          type: integer
          minimum: 0
          description: |-
            Specifies answered for this management call stats heatmap cell.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Numeric value | `0` or greater |
      required:
        - dayOfWeek
        - hour
        - calls
        - answered
    management__ErrorEnvelope:
      type: object
      required:
        - error
        - data
        - docs
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - param
            - request_id
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - permission_error
                - conflict_error
                - rate_limit_error
                - api_error
                - upstream_error
              description: |-
                Type discriminator for this object.

                <!-- polymorfa-input-table -->
                **Allowed values**
                | Value | Meaning |
                | --- | --- |
                | `invalid_request_error` | Invalid request error. |
                | `authentication_error` | Authentication error. |
                | `permission_error` | Permission error. |
                | `conflict_error` | Conflict error. |
                | `rate_limit_error` | Rate limit error. |
                | `api_error` | Api error. |
                | `upstream_error` | Upstream error. |
            code:
              type: string
              description: Stable failure code. Use this value for programmatic handling.
            message:
              type: string
              description: Safe explanation of the failure.
            param:
              type: string
              nullable: true
              description: |-
                Invalid request field, or null when no field applies.

                <!-- polymorfa-input-table -->
                **Accepted alternatives**
                | Alternative | Accepted input |
                | --- | --- |
                | Alternative 1 | Type: `string` |
                | Alternative 2 | `null` |
            request_id:
              type: string
              description: >-
                Matches the X-Request-Id response header. Include it when you
                contact support.
            request_log_url:
              type: string
              format: uri
              description: >-
                Console page that shows this request. Returned only to
                organization and project credentials whose request was logged.


                <!-- polymorfa-input-table -->

                **Value constraints**

                | Constraint | Accepted input |

                | --- | --- |

                | Format | `uri` |
          description: Error details returned when the operation fails.
        data:
          type: string
          nullable: true
          enum:
            - null
          description: |-
            Always null for a failed request.

            <!-- polymorfa-input-table -->
            **Allowed values**
            | Value | Meaning |
            | --- | --- |
            | `null` | Null. |

            **Accepted alternatives**
            | Alternative | Accepted input |
            | --- | --- |
            | Alternative 1 | Type: `string` |
            | Alternative 2 | `null` |
        docs:
          type: string
          format: uri
          description: |-
            Documentation link to this failure code.

            <!-- polymorfa-input-table -->
            **Value constraints**
            | Constraint | Accepted input |
            | --- | --- |
            | Format | `uri` |
  responses:
    management__BadRequest:
      description: A path, query, or request-body value did not pass validation.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
    management__Unauthorized:
      description: Missing/invalid credential for this audience.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
    management__Forbidden:
      description: Authenticated but lacks the required scope/role/audience.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
    management__CallStatsTooSlow:
      description: >-
        `service_unavailable`: the statistics took too long to compute. Narrow
        the range or filters and retry.
      headers:
        X-Request-Id:
          schema:
            type: string
          description: Stable request correlation identifier.
        Polymorfa-Version:
          schema:
            type: string
          description: API version applied to this response.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/management__ErrorEnvelope'
  securitySchemes:
    management__ApiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Send your team API key or project token as `Authorization: Bearer
        <token>`. The credential must have the required permissions. Project
        tokens can access only their own project.

````