> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Leave Balance

> Leave balances are read-optimized snapshots of a worker's leave position for a period

Use leave balances when you need the current answer to how much leave a worker has available in a
given period.

<Info>
  Balances are derived from leave transactions. Plane refreshes the ledger first, then recomputes
  the balance snapshot from those transactions.
</Info>

### Attributes

<ResponseField name="id" type="string">
  Unique identifier for the leave balance, for example `lvb_8kPqR2nYx1mVtD`.
</ResponseField>

<ResponseField name="worker" type="string">
  ID of the worker this balance belongs to.
</ResponseField>

<ResponseField name="policy" type="string | null">
  Representative leave policy for this balance. Returns `null` when the balance no longer has a
  primary policy pointer.
</ResponseField>

<ResponseField name="type" type="string">
  Leave type tracked by this balance.
</ResponseField>

<ResponseField name="unit" type="string">
  Unit used for all numeric values. One of `days` or `hours`.
</ResponseField>

<ResponseField name="period" type="object">
  Period window covered by this balance.

  <Expandable title="child attributes">
    <ResponseField name="starts" type="string">
      ISO 8601 start date for the balance period.
    </ResponseField>

    <ResponseField name="ends" type="string">
      ISO 8601 end date for the balance period.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="entitled" type="number">
  Total credited leave for the period from accrual and adjustment transactions, including future
  pending accruals.
</ResponseField>

<ResponseField name="used" type="number">
  Leave already used, based on past usage and reversal transactions.
</ResponseField>

<ResponseField name="scheduled" type="number">
  Approved leave scheduled for future dates in the period.
</ResponseField>

<ResponseField name="available" type="number">
  Net available balance for the period after entitled, carried, used, and scheduled leave are
  applied.
</ResponseField>

<ResponseField name="carried" type="number">
  Net carried amount, including carryover, expiry, forfeit, and payout effects.
</ResponseField>

<ResponseField name="created" type="string">
  ISO 8601 timestamp of when the balance was created.
</ResponseField>

<ResponseField name="updated" type="string">
  ISO 8601 timestamp of the most recent refresh of the balance.
</ResponseField>

<ResponseExample>
  ```json Leave Balance theme={null}
  {
    "id": "lvb_8kPqR2nYx1mVtD",
    "worker": "wr_CgcLakmx4guire",
    "policy": "lvp_Xk9mPq2vR8tn3e",
    "type": "vacation",
    "unit": "days",
    "period": {
      "starts": "2026-01-01",
      "ends": "2026-12-31"
    },
    "entitled": "25.0",
    "used": "5.5",
    "scheduled": "2.5",
    "available": "17.0",
    "carried": "0.0",
    "created": "2026-01-01T00:00:00Z",
    "updated": "2026-03-12T08:00:00Z"
  }
  ```
</ResponseExample>