> ## 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

> Leaves represent time away from work for a worker

Use leaves when you need the current time away from work for a
[Worker](/reference/workers/object), for example to power a calendar or schedule, or when you want
to record already-approved time off directly through the API. Each leave keeps its own status and
includes a summary of the request attached to it.

### Attributes

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

<ResponseField name="status" type="string">
  Current status of the leave. One of `requested`, `approved`, `declined`, or `cancelled`.
</ResponseField>

<ResponseField name="type" type="string">
  Type of leave. One of `paid_time_off`, `vacation`, `personal_time_off`, `public_holiday`,
  `sick_time_off`, `parental_leave`, `dependent_sick_leave`, `medical_leave`,
  `family_compassionate_leave`, `marriage_leave`, `bereavement`, `jury_duty`, `military_leave`,
  `working_time_reduction_rtt`, or `unpaid_time_off`.
</ResponseField>

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

<ResponseField name="starts" type="string">
  First day of the leave, formatted as an ISO 8601 date.
</ResponseField>

<ResponseField name="ends" type="string">
  Last day of the leave, formatted as an ISO 8601 date.
</ResponseField>

<ResponseField name="days" type="number">
  Total number of leave days. This value can be fractional.
</ResponseField>

<ResponseField name="hours" type="number">
  Total number of leave hours.
</ResponseField>

<ResponseField name="schedule" type="object">
  Dictionary of ISO 8601 dates to hours for each day in the leave, for example
  `{ "2026-04-14": 8, "2026-04-15": 8, "2026-04-16": 4 }`.
</ResponseField>

<ResponseField name="note" type="string | null">
  Optional note submitted with the leave. Returns `null` when no note was provided.
</ResponseField>

<ResponseField name="request" type="object">
  Summary of the request attached to this leave.

  <Expandable title="child attributes">
    <ResponseField name="id" type="string">
      The ID of the leave request, for example `lvr_6r3wLwX44s0Ak0bDkP5n2r7Q`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current request status. One of `requested`, `approved`, `declined`, or `cancelled`.
    </ResponseField>

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

    <ResponseField name="updated" type="string">
      ISO 8601 timestamp of the most recent update to the leave request.
    </ResponseField>
  </Expandable>
</ResponseField>

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

<ResponseField name="updated" type="string">
  ISO 8601 timestamp of the most recent update to the leave.
</ResponseField>

<ResponseExample>
  ```json Leave theme={null}
  {
    "id": "lv_1HPCXADYAhh5k1NMU0r1WUqs",
    "status": "approved",
    "type": "vacation",
    "worker": "wr_CgcLakmx4guire",
    "starts": "2026-04-14",
    "ends": "2026-04-16",
    "days": 2.5,
    "hours": 20,
    "schedule": {
      "2026-04-14": 8,
      "2026-04-15": 8,
      "2026-04-16": 4
    },
    "note": "Annual vacation",
    "request": {
      "id": "lvr_6r3wLwX44s0Ak0bDkP5n2r7Q",
      "status": "approved",
      "created": "2026-03-10T18:42:11Z",
      "updated": "2026-03-11T09:05:52Z"
    },
    "created": "2026-03-10T18:42:11Z",
    "updated": "2026-03-11T09:05:52Z"
  }
  ```
</ResponseExample>