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

# Conversation analytics for an inbox

> Aggregated conversation metrics for one inbox over a date range.

Response times are **business-hours aware** — they use the company's
configured business hours and holidays, the same basis as in-app reports, so
figures reconcile. `responseCount` is the number of replies the averages were
computed from.

Averages and rates are `null` rather than `0` when the window contains
nothing to measure. Automated/junk threads are excluded unless
`includeJunk=true`.

`sentiment` carries a numeric average plus the `coverage` it was computed
from, and `enabled` reports whether scoring is currently switched on for the
inbox. Scores exist only for threads the pipeline actually scored, so a
coverage of 40% means the average describes 40% of the window's threads.
`topics` lists the categories applied to threads in the window with their
thread counts.

Qualitative tone summaries (prose descriptions of tone) are not part of this
endpoint yet and are absent from the response rather than returned as null.




## OpenAPI

````yaml /openapi.yaml get /api/inboxes/{channelId}/analytics
openapi: 3.0.3
info:
  title: Aptly API
  version: '1.0'
  description: >
    The Aptly API lets you read and write cards on any Aptly board from external
    systems.


    All requests require an API key passed as the `x-token` header.

    API keys are scoped to your company and work across all boards.
servers:
  - url: https://core-api.getaptly.com
    description: Production
security:
  - ApiKeyHeader: []
paths:
  /api/inboxes/{channelId}/analytics:
    get:
      tags:
        - Inboxes
      summary: Conversation analytics for an inbox
      description: >
        Aggregated conversation metrics for one inbox over a date range.


        Response times are **business-hours aware** — they use the company's

        configured business hours and holidays, the same basis as in-app
        reports, so

        figures reconcile. `responseCount` is the number of replies the averages
        were

        computed from.


        Averages and rates are `null` rather than `0` when the window contains

        nothing to measure. Automated/junk threads are excluded unless

        `includeJunk=true`.


        `sentiment` carries a numeric average plus the `coverage` it was
        computed

        from, and `enabled` reports whether scoring is currently switched on for
        the

        inbox. Scores exist only for threads the pipeline actually scored, so a

        coverage of 40% means the average describes 40% of the window's threads.

        `topics` lists the categories applied to threads in the window with
        their

        thread counts.


        Qualitative tone summaries (prose descriptions of tone) are not part of
        this

        endpoint yet and are absent from the response rather than returned as
        null.
      operationId: getInboxAnalytics
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            type: string
          description: External channel meta ID (`meta.id`) of the inbox.
        - name: dateFrom
          in: query
          schema:
            type: string
            format: date-time
        - name: dateTo
          in: query
          schema:
            type: string
            format: date-time
          description: Exclusive. Range must not exceed 400 days.
        - name: groupBy
          in: query
          schema:
            type: string
            enum:
              - assignee
              - contactType
          description: >-
            Break the same metrics out per assignee, or per the counterpart's
            contact type. Omit for a single total.
        - name: includeJunk
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Aggregated metrics for the window.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/InboxAnalytics'
        '400':
          description: Invalid date range or `groupBy` value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or missing credential.
        '403':
          description: The authenticated user cannot reach this inbox.
        '404':
          description: Inbox not found in your company.
      security:
        - ApiKeyHeader: []
        - DelegateToken: []
        - PartnerBearer: []
components:
  schemas:
    InboxAnalytics:
      allOf:
        - $ref: '#/components/schemas/InboxMetricSet'
        - type: object
          properties:
            window:
              type: object
              properties:
                from:
                  type: string
                  format: date-time
                  nullable: true
                to:
                  type: string
                  format: date-time
                  nullable: true
            topics:
              type: array
              items:
                $ref: '#/components/schemas/InboxTopic'
            groupBy:
              type: string
              nullable: true
              enum:
                - assignee
                - contactType
            groups:
              type: array
              description: Present only when `groupBy` was supplied.
              items:
                allOf:
                  - type: object
                    properties:
                      key:
                        type: string
                        nullable: true
                        description: >-
                          Assignee user id or contact-type id. Null for
                          unassigned.
                      label:
                        type: string
                        nullable: true
                  - $ref: '#/components/schemas/InboxMetricSet'
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    InboxMetricSet:
      type: object
      description: >-
        Averages and rates are null (not 0) when the window has nothing to
        measure.
      properties:
        threadCount:
          type: integer
        contactCount:
          type: integer
          description: Distinct counterparts across the matching threads.
        volume:
          type: object
          properties:
            in:
              type: integer
            out:
              type: integer
            total:
              type: integer
        avgFirstResponseHrs:
          type: number
          nullable: true
        avgResponseHrs:
          type: number
          nullable: true
        responseCount:
          type: integer
          description: Replies the averages were computed from.
        oneTouchPct:
          type: number
          nullable: true
          description: Percentage of threads resolved with a single outbound.
        oneTouchCount:
          type: integer
        reopenRatePct:
          type: number
          nullable: true
        reopenedCount:
          type: integer
        noCustomerResponseCount:
          type: integer
          description: Threads where we sent something and never got a reply.
        awaitingOurReplyCount:
          type: integer
          description: Open threads where the counterpart spoke last.
        sentiment:
          $ref: '#/components/schemas/InboxSentiment'
    InboxTopic:
      type: object
      description: >-
        A topic (category) the enhancement pipeline or a teammate applied to
        threads in the window. Topics the company no longer defines are omitted.
      properties:
        topicId:
          type: string
        label:
          type: string
          nullable: true
        emoji:
          type: string
          nullable: true
        color:
          type: string
          nullable: true
        threadCount:
          type: integer
    InboxSentiment:
      type: object
      description: >-
        AI sentiment for the window. Scores are produced on write by the
        enhancement pipeline, only for inboxes where it is switched on, so
        `coverage` is always reported next to the average — an average over a
        fraction of the threads must not be read as covering all of them.
      properties:
        enabled:
          type: boolean
          description: >-
            Whether sentiment scoring is currently on for this inbox (org AI
            assistant + org sentiment + the inbox's own feature flag). Reported
            at the inbox level only, not per group.
        avg:
          type: number
          nullable: true
          description: Mean score across scored threads. Null when none were scored.
        coverage:
          type: object
          properties:
            scoredThreads:
              type: integer
            threadCount:
              type: integer
            pct:
              type: number
              nullable: true
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-token
    DelegateToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'Delegate token issued by the platform. Format: `DelegateToken <token>`'
    PartnerBearer:
      type: http
      scheme: bearer
      description: 'Partner token. Format: `Authorization: Bearer <token>`'

````