---
title: "Reads all Leaves"
method: GET
path: "/api/2026-10-01/resources/timeoff/leaves"
tags: ["Timeoff > Leave"]
---

# Reads all Leaves

`GET /api/2026-10-01/resources/timeoff/leaves`

## Request

- Base URL: `https://api.factorialhr.com`
- URL: `https://api.factorialhr.com/api/2026-10-01/resources/timeoff/leaves`
- Auth: one of:
  - OAuth 2
    - Authorization code: `https://id.factorialhr.com/oauth/authorize`
    - Token URL: `https://id.factorialhr.com/api/oauth/token` scopes: `time_off`
  - API key in header `x-api-key`

Reads all Leaves

## Query parameters

- `ids[]` string[]: Return only the leaves with these ids.
- `employee_ids[]` string[]: Return only the leaves of these employees.
- `leave_type_id[]` string[]: Return only the leaves of these leave types. Despite the singular name it takes a list.
- `to` string: Return only the leaves that had already started by this date (start date on or before it). Usable on its own; pair it with `from` for a window.
- `from` string: Return only the leaves that had not finished before this date, meaning they end on or after it or have no end date at all. Usable on its own; pair it with `to` for a window.
- `only_active` boolean: Retrieve only active leaves
- `include_deleted_leaves` boolean, required: Whether to include deleted leaves (not included by default if not specified)
- `approved` boolean: Set to true for leaves that were approved, false for leaves that were rejected. Leave it unset for every leave whatever its decision. Combining `approved: true` with `include_pending: true` returns approved and still-pending leaves together.
- `include_pending` boolean: Set to true to include leaves still awaiting a decision. On its own it returns ONLY the pending ones; alongside `approved: true` it returns approved and pending together.
- `include_leave_type` boolean: Retrieve leave types
- `include_duration` boolean: Retrieve leave duration
- `include_duration_by_day` boolean: Retrieve the per-day breakdown of the leave's duration (`duration_by_day_attributes`)
- `type_is_workable` boolean: Set to true for leaves whose leave type counts as worked time, false for those that do not. Leave it unset to get both.
- `type_is_payable` boolean: Set to true for leaves whose leave type is paid, false for unpaid ones. Leave it unset to get both.
- `forced_finish_on` string: Caps the per-day duration walk at this date. For endless leaves (`finish_on = nil`) it pins the walk end; for closed leaves whose `finish_on` sits past this date it truncates the walk. Never extends a leave past its real `finish_on`. Must fall inside the read window (from/to or overlaps_range_from/overlaps_range_to).

## Response `200`

OK

- object
  - `data` TimeoffLeave[]
    - `id` string, required: Identifier of the Leave
    - `company_id` string, required: ID of the company the leave belongs to
    - `employee_id` string, required: ID of the employee taking the leave
    - `start_on` string, required: First day of the leave
    - `finish_on` string: Last day of the leave (inclusive); null while an open-ended leave has no end yet
    - `half_day` string: Which half of the day a half-day leave covers — `beginning_of_day` or `end_of_day`; null for full-day leaves
    - `description` string: Free-text description of the leave
    - `reason` string: The reason provided by the employee for taking the leave
    - `leave_type_id` string: ID of the leave type this leave is of
    - `leave_type_name` string: Denormalised name of the leave type
    - `approved` boolean: Tri-state approval status — true = approved, false = rejected, null = pending approval
    - `employee_full_name` string: The full name of the employee taking the leave
    - `start_time` string: The start time of the leave
    - `hours_amount_in_cents` integer: Total hours the leave consumes, in hundredths of an hour (e.g. 800 = 8 hours); set for hourly leaves
    - `updated_at` string, required: The updated at date of the leave
    - `created_at` string: The created at date of the leave
    - `deleted_at` string: The date when the leave was deleted
    - `duration_attributes` string: The duration attributes of the leave
    - `duration_by_day_attributes` object: Per-day breakdown of the leave's workable and used units, keyed by calendar date. Populated only when the read requests `include_duration_by_day=true`; null otherwise.
      - `workable_units_by_day` object, required
        - `days` unknown, required
        - `hours` unknown, required
      - `used_units_by_day` object, required
        - `days` unknown, required
        - `hours` unknown, required
    - `days_taken` number, required: Number of days taken for paid leave. Reflects the summed per-day used total when the per-day breakdown is computed; otherwise the leave's calendar-day duration.
  - `meta` PagedIndexMeta
    - `start_cursor` string
    - `end_cursor` string
    - `has_previous_page` boolean, required
    - `has_next_page` boolean, required
    - `limit` integer, required
    - `total` integer, required

## Changes

- **2026-11-03** `83ac9aa1de50`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/factorialhr/apis/factorial-api/changes/api/2026-10-01/resources/timeoff/leaves/get.md)

---

[API](https://skmtc.dev/factorialhr/apis/factorial-api.md) - [All operations](https://skmtc.dev/factorialhr/apis/factorial-api/llms.txt) - [OpenAPI document](https://skmtc.dev/factorialhr/apis/factorial-api/revisions/83ac9aa1de50?raw)