---
title: "List organization time off balances"
method: GET
path: "/v2/organizations/{organization_id}/time_off_balances"
tags: ["time_off_balances"]
---

# List organization time off balances

`GET /v2/organizations/{organization_id}/time_off_balances`

## Request

- Base URL: `https://api.hubstaff.com`
- URL: `https://api.hubstaff.com/v2/organizations/{organization_id}/time_off_balances`
- Auth: OAuth 2
  - Authorization code: `https://account.hubstaff.com/authorizations/new`
  - Token URL: `https://account.hubstaff.com/access_tokens` scopes: `hubstaff:read`, `hubstaff:write`
- TypeScript: <https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/docs/v2/organizations/:organization_id/time_off_balances/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns time off balances for the given organization.

Each entry represents one user's balance for one time off policy in the requested year.

Use `year` to query balances for a specific year (defaults to current year in the organization's timezone).

Use `include[]` to sideload related users and time_off_policies.

## Path parameters

- `organization_id` integer, required

## Query parameters

- `page_start_id` integer
- `page_limit` integer
- `search` string
- `user_ids` integer[]
- `time_off_policy_ids` integer[]
- `year` integer
- `include` string[]

## Response `200`

A list of time off balances

- object
  - `time_off_balances` TimeOffBalance[]
    - `user_id` integer, required: User ID
    - `time_off_policy_id` integer, required: Time off policy ID
    - `policy_name` string, required: Time off policy name
    - `amount` integer, required: Balance amount in seconds

## Other responses

- `400`: Invalid parameters
- `401`: Unauthorized
- `403`: API access is only for organizations on an active plan
- `404`: Could not find record
- `429`: Rate limit exceeded

## Changes

- **2026-11-06** `c6b90e4e4bdc`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hubstaff/apis/hubstaff-v2-api/changes/v2/organizations/:organization_id/time_off_balances/get.md)

---

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