> ## 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.

# Volume and response-time trends for an inbox

> A gap-free time series for one inbox, rolled up server-side by day, week,
month or quarter. Both `dateFrom` and `dateTo` are required (max 400 days);
`dateTo` is exclusive. Periods with no activity are returned with zero volume
rather than omitted, so the series can be charted directly.

All bucketing is UTC. Weeks start Monday (ISO) and are keyed by that Monday's
date, so week keys sort alongside day keys.

**Two bucketing bases, deliberately:** `volume` counts messages sent or
received *during* the period, while `threadCount` and the response/rate
figures describe threads whose *last activity* fell in the period. Response
times carry no per-message timestamps, so they can't be attributed to a
single day of a long-running thread. Do not divide `volume` by `threadCount`.

Averages are combined from underlying sums and counts, so a quiet day never
carries the same weight as a busy one. `responseCount` is the number of
replies behind `avgResponseHrs`.




## OpenAPI

````yaml /openapi.yaml get /api/inboxes/{channelId}/trends
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}/trends:
    get:
      tags:
        - Inboxes
      summary: Volume and response-time trends for an inbox
      description: >
        A gap-free time series for one inbox, rolled up server-side by day,
        week,

        month or quarter. Both `dateFrom` and `dateTo` are required (max 400
        days);

        `dateTo` is exclusive. Periods with no activity are returned with zero
        volume

        rather than omitted, so the series can be charted directly.


        All bucketing is UTC. Weeks start Monday (ISO) and are keyed by that
        Monday's

        date, so week keys sort alongside day keys.


        **Two bucketing bases, deliberately:** `volume` counts messages sent or

        received *during* the period, while `threadCount` and the response/rate

        figures describe threads whose *last activity* fell in the period.
        Response

        times carry no per-message timestamps, so they can't be attributed to a

        single day of a long-running thread. Do not divide `volume` by
        `threadCount`.


        Averages are combined from underlying sums and counts, so a quiet day
        never

        carries the same weight as a busy one. `responseCount` is the number of

        replies behind `avgResponseHrs`.
      operationId: getInboxTrends
      parameters:
        - name: channelId
          in: path
          required: true
          schema:
            type: string
          description: External channel meta ID (`meta.id`) of the inbox.
        - name: dateFrom
          in: query
          required: true
          schema:
            type: string
            format: date-time
        - name: dateTo
          in: query
          required: true
          schema:
            type: string
            format: date-time
          description: Exclusive. Range must not exceed 400 days.
        - name: granularity
          in: query
          schema:
            type: string
            enum:
              - day
              - week
              - month
              - quarter
            default: day
        - name: includeJunk
          in: query
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Gap-free trend series, oldest period first.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      granularity:
                        type: string
                        enum:
                          - day
                          - week
                          - month
                          - quarter
                      window:
                        type: object
                        properties:
                          from:
                            type: string
                            format: date-time
                          to:
                            type: string
                            format: date-time
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/InboxTrendPeriod'
        '400':
          description: Missing/invalid window, or invalid granularity.
          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:
    InboxTrendPeriod:
      type: object
      properties:
        period:
          type: string
          description: >-
            Period key. `YYYY-MM-DD` for day and week (week = the Monday it
            starts), `YYYY-MM` for month, `YYYY-Qn` for quarter.
        volume:
          type: object
          description: Messages sent or received during this period.
          properties:
            in:
              type: integer
            out:
              type: integer
            total:
              type: integer
        threadCount:
          type: integer
          description: Threads whose last activity fell in this period.
        avgResponseHrs:
          type: number
          nullable: true
          description: Business hours. Null when the period had no replies.
        responseCount:
          type: integer
          description: Replies behind avgResponseHrs.
        avgFirstResponseHrs:
          type: number
          nullable: true
        oneTouchPct:
          type: number
          nullable: true
        reopenRatePct:
          type: number
          nullable: true
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  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>`'

````