---
title: "Get Time Off Balance"
method: GET
path: "/api/v1/employees/{employeeId}/time_off/calculator"
tags: ["Time Off", "Public API"]
---

# Get Time Off Balance

`GET /api/v1/employees/{employeeId}/time_off/calculator`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/employees/{employeeId}/time_off/calculator`
- Auth: one of:
  - HTTP basic
  - OAuth 2
    - Authorization code: `/authorize.php`
    - Token URL: `/token.php` scopes: `time_off`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/employees/:employeeId/time_off/calculator/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns time off balances for an employee across all assigned categories as of a given date. Each category's balance is calculated by summing all historical balance events (accruals, manual adjustments, used time off, and carry-over events) plus any future accruals and adjustments up to the specified date. To get current balances, pass today's date; to project future balances, pass a future date. Response defaults to XML unless Accept: application/json is provided.

**This endpoint does not accept the `0` self sentinel.** Unlike Get Employee (`get-employee`), passing `0` as `employeeId` returns `404` with an empty body and the header `x-bamboohr-error-message: Employee not found`. To read the authenticated caller's own balances, first resolve their internal employee ID with `get-employee` using the id `0`, then call this endpoint with that ID.

**Permissions.** Access is gated on the same Time Off tab view permission the web application uses. That permission is configured per access level and is **not** implied by the reporting structure: being an employee's manager does not by itself grant it, and a manager may receive `403` for their own direct reports. A caller without permission for the target employee receives an explicit `403` rather than an empty success, so the two cases are distinguishable: a `403` means access was denied, while an empty array with `200` means the employee has no assigned policies among the time off types this caller can view. Do not read a `403` as the employee having no time off, and do not read an empty array as a permission problem.

Because the categories returned are limited to the time off types the caller can view for that employee, two callers can legitimately receive different subsets for the same person. Treat the returned set as what this caller may see, not as the employee's complete policy list. `list-employee-time-off-policies-v1_1` is the companion endpoint for the underlying assignments and is gated on the same permission.

A category returning `0.00` is not an error and does not necessarily mean the time cannot be requested. Discretionary policies (for example Bereavement or FMLA) are granted as needed rather than accrued, so they normally report a zero balance while still being available to request. Use `policyType` to distinguish `accruing` from `discretionary` before characterizing a zero.

OAuth Scopes: time_off

## Path parameters

- `employeeId` string, required

## Query parameters

- `end` string, date
- `precision` integer

## Headers

- `AcceptHeaderParameter` 'application/xml' | 'application/json'

## Response `200`

An array of time off balance entries, one per assigned time off type.

- object[]
  - `timeOffType` string: The ID of the time off type.
  - `name` string: The name of the time off type.
  - `units` string: The unit of measurement for the balance (e.g. 'hours' or 'days').
  - `balance` string: The calculated time off balance as of the specified date, rounded using `precision`.
  - `end` string, date: The date the balance was calculated as of, in YYYY-MM-DD format.
  - `policyType` 'accruing' | 'discretionary' | 'manual': The type of time off policy assigned to the employee for this time off type.
  - `usedYearToDate` string: The amount of time off used year-to-date as of the specified date, rounded using `precision`.

## Other responses

- `401`: Unauthorized. Invalid API credentials.
- `403`: Insufficient permissions to view this employee's time off.
- `404`: Employee not found. Some clients may receive an empty HTML response body for this legacy error case.

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - added the non-success response with the status `403`

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/employees/:employeeId/time_off/calculator/get.md)

---

[API](https://skmtc.dev/bamboohr/apis/bamboohr-api.md) - [All operations](https://skmtc.dev/bamboohr/apis/bamboohr-api/llms.txt) - [OpenAPI document](https://skmtc.dev/bamboohr/apis/bamboohr-api/revisions/922fc15f43a7?raw)