---
title: "Leave balances"
method: GET
path: "/leave-balances"
tags: ["absences"]
---

# Leave balances

`GET /leave-balances`

## Request

- Base URL: `https://api.taktovka.com/v1`
- URL: `https://api.taktovka.com/v1/leave-balances`
- Auth: HTTP bearer

Annual leave of a year per person: the entitlement and what was carried over as the employer entered them, what approved and waiting requests use, and what is left. Working days in SK, hours in CZ. People without an entitlement for the year are not listed. `next_cursor` is always null. Counts as 5 requests against the rate limit. Runs one at a time per company; a second call while one is running answers 429 with retry_after.

## Query parameters

- `year` integer
- `employee` string, uuid

## Response `200`

OK

- object
  - `data` LeaveBalance[], required
    - `employee_id` string, uuid, required
    - `year` integer, required
    - `unit` 'day' | 'hour', required
    - `entitled` number, required
    - `carried_over` number, required
    - `used` number, required: Approved leave of the year, past and planned
    - `pending` number, required: Requests of the year still waiting for a decision
    - `remaining` number, required: Entitled plus carried over less used; may be below zero
  - `next_cursor` string, nullable, required

## Other responses

- `400`: validation_failed, range_too_long or key_in_query
- `401`: unauthenticated, invalid_key, key_revoked or key_expired
- `403`: insufficient_scope (with required_scope)
- `429`: rate_limited (with retry_after and a Retry-After header)

---

[API](https://skmtc.dev/taktovka/apis/taktovka-api.md) · [All operations](https://skmtc.dev/taktovka/apis/taktovka-api/llms.txt) · [OpenAPI document](https://skmtc.dev/taktovka/apis/taktovka-api/revisions/612199b365e1?raw)