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

# List employees hours bag aggregate balance

> Returns the aggregated hours bag balance per employee for a given date range. Includes overtime balance, paid seconds, vacation-compensated seconds and total pending seconds.



## OpenAPI

````yaml GET /schedule/v1/employees-hours-bags
openapi: 3.0.0
info:
  description: ''
  version: 3.0.0
  title: Sesame Public API
servers:
  - url: https://api-{region}.sesametime.com
    variables:
      region:
        default: eu1
security: []
tags: []
paths:
  /schedule/v1/employees-hours-bags:
    get:
      tags:
        - Hours Bag
      summary: List employees hours bag aggregate balance
      description: >-
        Returns the aggregated hours bag balance per employee for a given date
        range. Includes overtime balance, paid seconds, vacation-compensated
        seconds and total pending seconds.
      operationId: ListEmployeesHoursBags
      parameters:
        - name: from
          in: query
          description: Start date of the aggregation period (inclusive)
          required: true
          schema:
            type: string
            format: date
            example: '2026-03-01'
        - name: to
          in: query
          description: >-
            End date of the aggregation period (inclusive). Must be greater than
            or equal to 'from'.
          required: true
          schema:
            type: string
            format: date
            example: '2026-03-31'
        - name: search
          in: query
          description: Filter employees by name or email (partial match)
          schema:
            type: string
        - name: status[in]
          in: query
          description: Filter by employee status
          schema:
            type: string
            example: active,inactive
        - name: employeeIds[in]
          in: query
          description: Filter by a comma-separated list of employee IDs
          schema:
            type: string
            example: uuid1,uuid2
        - name: limit
          in: query
          description: Limit results by page
          schema:
            type: integer
            default: 20
        - name: page
          in: query
          description: Request a specific page
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: Array of employee hours bag aggregates
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        employee:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: Employee identifier
                            name:
                              type: string
                              description: Employee full name
                        from:
                          type: string
                          format: Y-m-d
                          example: '2020-01-01'
                        to:
                          type: string
                          format: Y-m-d
                          example: '2020-01-01'
                        overtimeBalanceSeconds:
                          type: integer
                          description: >-
                            Net overtime balance (computed + adjusted rule
                            seconds + day off seconds), in seconds
                          example: 5100
                        paidSeconds:
                          type: integer
                          description: Total paid (remunerated) seconds in the period
                          example: 900
                        holidayCompensatedSeconds:
                          type: integer
                          description: >-
                            Total seconds compensated as vacation/holidays in
                            the period
                          example: 300
                        totalPendingSeconds:
                          type: integer
                          description: >-
                            Outstanding seconds (overtimeBalance - paid -
                            holidayCompensated)
                          example: 3900
                  meta:
                    type: object
                    properties:
                      currentPage:
                        type: integer
                        example: 1
                      lastPage:
                        type: integer
                        example: 1
                      total:
                        type: integer
                        example: 1
                      perPage:
                        type: integer
                        example: 1
        '400':
          description: Bad Request - The request was invalid or cannot be served
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message describing what went wrong
                    example: Validation failed for the provided data
                  errors:
                    type: array
                    description: List of specific validation errors
                    items:
                      type: object
                      properties:
                        field:
                          type: string
                          description: The field that caused the error
                          example: questionId
                        message:
                          type: string
                          description: Specific error message for the field
                          example: This value is not a valid UUID.
              example:
                message: Validation failed
                errors:
                  - field: questionId
                    message: This value is not a valid UUID.
                  - field: answer
                    message: This field is required for text-based questions.
        '401':
          description: Unauthorized - Invalid or missing API Key
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Error message indicating authentication failure
                    example: Invalid or missing API Key
                  code:
                    type: string
                    description: Error code for programmatic handling
                    example: UNAUTHORIZED
              example:
                message: Invalid or missing API Key
                code: UNAUTHORIZED
      security:
        - Bearer: []
components:
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````