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

> Returns calendars in your Plane workspace.

Use this endpoint to discover calendar IDs before listing or retrieving
[calendar events](/reference/calendar-events/object). Filter by `purpose` to find system
calendars such as the holidays or time-off calendar without matching on name.

### Parameters

<ParamField query="purpose" type="string">
  Only return calendars tagged with this purpose. Known values include `holidays`, `leaves`,
  `anniversaries`, and `starting`. This list is not exhaustive.
</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 calendar ID.
</ParamField>

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

### Returns

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

<ResponseExample>
  ```json Response theme={null}
  {
    "calendars": [
      {
        "id": "cal_cNqYX2J3s9bI2Aa",
        "object": "calendar",
        "name": "Company Events",
        "description": "Company-wide events and meetings",
        "purpose": [ "holidays" ],
        "metadata": {},
        "created": "2024-01-15T00:00:00Z",
        "updated": "2024-02-01T00:00:00Z"
      }
    ]
  }
  ```
</ResponseExample>