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

# Get bucketed per-agent and aggregate availability timeline

> Returns availability state buckets over a time window for charting. Each bucket carries the dominant state per agent and the aggregate state across the org/department, plus per-agent online / available / at-capacity durations within the bucket. Defaults to the last 24 hours with 15-minute buckets if start/end/bucketMinutes are omitted.



## OpenAPI

````yaml /api-reference/openapi.yaml get /api/escalation-dashboard/availability-timeline
openapi: 3.0.3
info:
  title: Tether Relay and Tether API
  version: 1.0.0
  description: >-
    Route-derived OpenAPI contract generated from tether-relay backend sources.
    Regenerate with scripts/sync-openapi-from-backend.mjs.
servers:
  - url: https://your-instance.example.com
    description: Production
  - url: http://localhost:2212
    description: Local API service
security: []
tags:
  - name: AI
  - name: Applications
  - name: Approval
  - name: Auth
  - name: Automations
  - name: Calls
  - name: Campaigns
  - name: Contact Analytics
  - name: Contact Metrics
  - name: Contact Notes
  - name: Contacts
  - name: Conversation Monitor
  - name: Conversations
  - name: Departments
  - name: Email
  - name: Escalation Dashboard
  - name: Event Logs
  - name: Google Sheets
  - name: Marketplace
  - name: Messages
  - name: Notification Sounds
  - name: Notifications
  - name: Org Snapshots
  - name: Organizations
  - name: Outreach
  - name: Outreach Metrics
  - name: Outreach Sources
  - name: Pipelines
  - name: Processes
  - name: Prompts
  - name: Reminders
  - name: Sms
  - name: Templates
  - name: Traces
  - name: Training
  - name: Upload
  - name: User Snapshots
  - name: Users
  - name: Vertical
  - name: Webchats
  - name: Webhook
paths:
  /api/escalation-dashboard/availability-timeline:
    get:
      tags:
        - Escalation Dashboard
      summary: Get bucketed per-agent and aggregate availability timeline
      description: >-
        Returns availability state buckets over a time window for charting. Each
        bucket carries the dominant state per agent and the aggregate state
        across the org/department, plus per-agent online / available /
        at-capacity durations within the bucket. Defaults to the last 24 hours
        with 15-minute buckets if start/end/bucketMinutes are omitted.
      operationId: get_availability_timeline
      parameters:
        - in: query
          name: departmentId
          required: false
          schema:
            type: string
          description: >-
            Optional department filter. ADMIN/SUPERADMIN may pass any
            departmentId; DEPARTMENT_HEAD is implicitly scoped to their own
            department and any other value is ignored.
        - in: query
          name: start
          required: false
          schema:
            type: string
            format: date-time
          description: ISO-8601 start of the window. Defaults to end - 24h.
        - in: query
          name: end
          required: false
          schema:
            type: string
            format: date-time
          description: ISO-8601 end of the window. Defaults to now.
        - in: query
          name: bucketMinutes
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 120
            default: 15
            description: Bucket size in minutes. Clamped to [1, 120].
      responses:
        '200':
          description: Availability timeline returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailabilityTimelineResponse'
        '400':
          description: Invalid start or end date
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationDashboardError'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationDashboardError'
        '500':
          description: Error fetching availability timeline
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EscalationDashboardError'
      security:
        - bearerAuth: []
components:
  schemas:
    AvailabilityTimelineResponse:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          $ref: '#/components/schemas/AvailabilityTimelineData'
      required:
        - success
        - data
      additionalProperties: false
      example:
        success: true
        data:
          start: '2026-05-18T00:00:00.000Z'
          end: '2026-05-18T15:00:00.000Z'
          bucketMinutes: 15
          buckets:
            - '2026-05-18T14:30:00.000Z'
          agents:
            5f7b1c2e8a1d4e0012c3b4a5:
              - available
          aggregate: []
          users: []
    EscalationDashboardError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        message:
          type: string
        error:
          type: string
      required:
        - success
        - message
      additionalProperties: true
      example:
        success: false
        message: Access denied
    AvailabilityTimelineData:
      type: object
      properties:
        start:
          type: string
          format: date-time
        end:
          type: string
          format: date-time
        bucketMinutes:
          type: integer
        buckets:
          type: array
          items:
            type: string
            format: date-time
          description: ISO-8601 timestamps for the start of each bucket.
        agents:
          type: object
          description: >-
            Map of userId -> dominant TimelineState per bucket (same length as
            `buckets`).
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/AvailabilityTimelineState'
        aggregate:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityAggregateBucket'
        users:
          type: array
          items:
            $ref: '#/components/schemas/AvailabilityTimelineUser'
      required:
        - start
        - end
        - bucketMinutes
        - buckets
        - agents
        - aggregate
        - users
      additionalProperties: false
      example:
        start: '2026-05-18T00:00:00.000Z'
        end: '2026-05-18T15:00:00.000Z'
        bucketMinutes: 15
        buckets:
          - '2026-05-18T14:30:00.000Z'
          - '2026-05-18T14:45:00.000Z'
        agents:
          5f7b1c2e8a1d4e0012c3b4a5:
            - available
            - at_capacity
        aggregate:
          - state: available
            onlineUserIds:
              - 5f7b1c2e8a1d4e0012c3b4a5
            availableUserIds:
              - 5f7b1c2e8a1d4e0012c3b4a5
            atCapacityUserIds: []
            userDurations: []
        users:
          - _id: 5f7b1c2e8a1d4e0012c3b4a5
            fullName: Sam Patel
            email: sam.patel@acme.example
    AvailabilityTimelineState:
      type: string
      enum:
        - available
        - at_capacity
        - online
        - offline
        - mixed
      example: available
    AvailabilityAggregateBucket:
      type: object
      properties:
        state:
          $ref: '#/components/schemas/AvailabilityTimelineState'
        onlineUserIds:
          type: array
          items:
            type: string
        availableUserIds:
          type: array
          items:
            type: string
        atCapacityUserIds:
          type: array
          items:
            type: string
        userDurations:
          type: array
          items:
            type: object
            properties:
              userId:
                type: string
              onlineMs:
                type: integer
              availableMs:
                type: integer
              atCapacityMs:
                type: integer
            required:
              - userId
              - onlineMs
              - availableMs
              - atCapacityMs
            additionalProperties: false
      required:
        - state
        - onlineUserIds
        - availableUserIds
        - atCapacityUserIds
        - userDurations
      additionalProperties: false
      example:
        state: available
        onlineUserIds:
          - 5f7b1c2e8a1d4e0012c3b4a5
          - 6a8c2d3f9b1e5a0023d4c5b6
        availableUserIds:
          - 5f7b1c2e8a1d4e0012c3b4a5
        atCapacityUserIds: []
        userDurations:
          - userId: 5f7b1c2e8a1d4e0012c3b4a5
            onlineMs: 900000
            availableMs: 720000
            atCapacityMs: 0
    AvailabilityTimelineUser:
      type: object
      properties:
        _id:
          type: string
        fullName:
          type: string
        email:
          type: string
      required:
        - _id
        - fullName
        - email
      additionalProperties: false
      example:
        _id: 5f7b1c2e8a1d4e0012c3b4a5
        fullName: Sam Patel
        email: sam.patel@acme.example
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````