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

> Returns leave requests in your Plane workspace.

Use this endpoint when you need leave request history, including requests that are still pending or
that were later declined or cancelled. Results are returned newest first, sorted by `created` and
then by `id`.

### Parameters

<ParamField query="starts" type="string">
  Only return leave requests whose leave 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 leave requests whose leave start date falls on or before this date. Use an ISO 8601
  date such as `2026-04-30`.
</ParamField>

<ParamField query="status" type="string">
  Only return leave requests in this status. One of `requested`, `approved`, `declined`, or
  `cancelled`.
</ParamField>

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

<ParamField query="leave" type="string">
  Only return leave requests for this leave ID.
</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 request when any part of its leave falls
inside that date window.

### Request

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

### Returns

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

<ResponseExample>
  ```json Response theme={null}
  {
    "leave_requests": [
      {
        "id": "lvr_6r3wLwX44s0Ak0bDkP5n2r7Q",
        "status": "requested",
        "leave": {
          "id": "lv_1HPCXADYAhh5k1NMU0r1WUqs",
          "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"
        },
        "created": "2026-03-10T18:42:11Z",
        "updated": "2026-03-10T18:42:11Z"
      }
    ],
    "cursor": "eyJpZCI6Imx2cl82cjN3THdYNDRzMEFrMGJEa1A1bjJyN1EifQ=="
  }
  ```
</ResponseExample>