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

# List leaves

> Returns leaves in your Plane workspace.

Use this endpoint when you need leave for scheduling, attendance, or calendar sync use cases.
Results are returned newest first, sorted by `created` and then by `id`.

### Parameters

<ParamField query="starts" type="string">
  Only return leaves whose end date falls on or after this date. Use an ISO 8601 date such as
  `2026-04-01`.
</ParamField>

<ParamField query="ends" type="string">
  Only return leaves whose start date falls on or before this date. Use an ISO 8601 date such as
  `2026-04-30`.
</ParamField>

<ParamField query="worker" type="string">
  Only return leaves for this worker ID.
</ParamField>

<ParamField query="status" type="string">
  Only return leaves in this status. One of `requested`, `approved`, `declined`, `cancelled`, or
  `all`. Passing `all` returns leaves of every status. If you don't provide a value, only approved
  leaves are returned.
</ParamField>

<ParamField query="type" type="string">
  Only return leaves of this type.
</ParamField>

<ParamField query="limit" type="number">
  A limit on the number of objects to be returned. Limit can range between 1 and 100, and the
  default is 10.
</ParamField>

<ParamField query="cursor" type="string">
  A value from a previous response that lets you fetch the next page.
</ParamField>

<ParamField query="starting_after" type="string">
  Return results after this object ID.
</ParamField>

<ParamField query="ending_before" type="string">
  Return results before this object ID.
</ParamField>

If you send `starts` or `ends`, Plane returns a leave when any part of it falls inside that date
window.

### Request

<RequestExample>
  ```bash cURL theme={null}
  curl -G https://api.plane.com/v1/leaves \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</RequestExample>

### Returns

Returns a dictionary with a `leaves` property that contains an array of
[Leave](/reference/leaves/object) objects. If no matching leaves exist, the array is empty.

<ResponseExample>
  ```json Response theme={null}
  {
    "leaves": [
      {
        "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"
      }
    ],
    "cursor": "eyJpZCI6Imx2XzFIUENYQURZQWhoNWsxTk1VMHIxV1VxcyJ9"
  }
  ```
</ResponseExample>