---
title: "Reads all Allowance stats"
method: GET
path: "/api/2026-10-01/resources/timeoff/allowance_stats"
tags: ["Timeoff > AllowanceStat"]
---

# Reads all Allowance stats

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

## Request

- Base URL: `https://api.factorialhr.com`
- URL: `https://api.factorialhr.com/api/2026-10-01/resources/timeoff/allowance_stats`
- 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`

Retrieves the employee time off counters for a specific allowance with a reference date. Read without employee_ids it pages by employee with a cursor: limit and meta.total count employees rather than stats, so a page carries every stat those employees have, and the page parameter is not supported there - follow meta.end_cursor instead.

## Query parameters

- `ids[]` string[]: A virtual ID for the allowance stat, composed of employee_id/allowance_id/reference_date. Cannot be used to fetch this resource.
- `employee_ids[]` string[]: IDs of the employees to read allowance stats for, at most 25 per request. Leave it empty to read every employee you have access to. Naming an employee you cannot access returns an empty page rather than the stats for the others.
- `allowance_ids[]` string[]: Filter the stats by these allowance IDs
- `reference_date` string: The reference date to calculate the allowance stats. If not provided, it will use today's date.
- `simulate_policy_change_to_id` string: When provided, computes the stats as if the employee were moved to this target time off policy effective the day AFTER reference_date, so pass the day before the change date - for a change effective on 2026-08-03, send reference_date=2026-08-02. This truncates the source policy's current cycle at that boundary so available_days reflects the prorated balance that would actually transfer or be discarded on the change, rather than the full entitlement. Purely a read - nothing is persisted. Requires the policy timeline feature; without it the result is identical to an un-simulated read. Can only be used together with employee_ids, because a simulation needs every employee in the read to belong to the target policy's company - which a company-wide read cannot guarantee.

## Response `200`

OK

- object
  - `data` TimeoffAllowanceStatsNew[]
    - `id` string, required: A virtual ID for the allowance stat, composed of employee_id/allowance_id/reference_date. Cannot be used to fetch this resource.
    - `allowance_id` string, required: ID of the allowance these stats belong to.
    - `employee_id` string, required: ID of the employee these stats belong to.
    - `year` integer, required: Calendar year used to scope cycle calculations.
    - `cycles` object[], required: Array of cycle objects describing each accrual period for the allowance.
      - `id` string, required
      - `start_at` string, required
      - `end_at` string, required
      - `regular_start_at` string, required
      - `regular_end_at` string, required
      - `allowance_id` string, required
    - `cycle_carry_overs` object[], required: Carry over entries between cycles, typed as an array of CycleCarryOver value objects.
      - `from_cycle_ending_on` string, required: The date on which the source cycle ended, from which these carry-over units originate.
      - `expire_in_months` integer: Number of months after the cycle end date before carry-over units expire. Null means no expiry.
      - `non_expire` boolean, required: When true, carry-over units never expire regardless of expire_in_months.
      - `total` string, required: Total carry-over units available from the source cycle (days or hours depending on allowance type).
      - `used` object[], required: Individual leave entries that consumed carry-over units.
        - `date` string, required: Calendar day on which the leave was taken.
        - `amount` string, required: Units consumed on that day (days or hours).
      - `accumulated` string, required: Total carry-over units accumulated (may differ from total when caps apply).
      - `expired` string, required: Carry-over units that have expired.
      - `taken` string, required: Carry-over units already consumed by leave.
    - `accumulated_carry_over` string, required: Total carried over units accumulated from previous cycles.
    - `available_days` string, required: Remaining usable allowance units at the reference date, after usage, carry-over, and incidence adjustments.
    - `total_accrued_units` string, required: Total accrued/generated allowance units up to the reference date.
    - `total` string, required: Total entitlement for the cycle used by the Total row in counters (accrued + carry over + incidences, with backend cap/rounding rules applied before incidences).
    - `incidences` string, required: Sum of incidence units (adjustments) applied to this allowance.
    - `accrued_incidences` string, required: Sum of incidence units scoped to 'accrued' target balance for the current cycle, filtered by cycle coverage rules.
    - `available_incidences` string, required: Sum of incidence units scoped to non-accrued target balances for the current cycle, filtered by cycle coverage rules.
    - `max_balance_cap` string: Maximum balance cap enforced by policy (null if unlimited or no cap).
    - `policy_allowance` string, required: Base policy entitlement for the cycle in allowance units (days or hours depending on allowance setup), before proration and adjustments.
    - `prorated_allowance_days` string, required: Allowance days after proration based on employee tenure or configuration.
    - `total_in_decimal` string: Total allowance units in decimal form (null if not computed for the reference date yet).
    - `used_carry_over` string, required: Units from carry over already consumed.
    - `used_days` string, required: Total used days (converted from units) up to the reference date.
    - `used_units_until_reference_date` string, required: Units consumed strictly until the given reference date (excludes future approved leaves).
    - `outstanding_units` string, required: Pending units scheduled (approved in the future) not yet counted as used until the reference date.
  - `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/allowance_stats/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)