---
title: "List calendar events with filters (Admin)"
description: "Retrieve list of calendar events with optional filtering. Requires admin authentication."
---

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

Path: Channel Automation API › Calendar

`GET /api/calendar/events`

Retrieve list of calendar events with optional filtering. Requires admin authentication.

## Authentication

Requires one of the following:

- `BearerAuth`, http, header `Authorization`, format `JWT`
- `ApiKeyAuth`, apiKey, in header, header `X-API-Key`, format `API_KEY`

## Query parameters

- `workspace_id` (`get/api/calendar/events.query.workspace_id`; string, optional) — Filter by workspace ID
  - example `"15213"`
- `admin_id` (`get/api/calendar/events.query.admin_id`; string, optional) — Filter by admin/creator ID
  - example `"464cf603-5a10-4470-a100-331fc0766680"`
- `start_date` (`get/api/calendar/events.query.start_date`; string, optional) — Filter events from this date
  - format `date`; example `"2025-07-10"`
- `end_date` (`get/api/calendar/events.query.end_date`; string, optional) — Filter events until this date
  - format `date`; example `"2025-07-15"`

## Code samples

### cURL

```bash
curl --request GET \
  --url https://api.channelautomation.com/api/calendar/events \
  --header 'Authorization: Bearer <token>'
```

### TypeScript

```typescript
const url = 'https://api.channelautomation.com/api/calendar/events';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.channelautomation.com/api/calendar/events"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)
```

## Responses

### 200

Events retrieved successfully

#### Example

```json
{
  "success": true,
  "events": [
    {
      "id": "appointment-uuid",
      "contact_id": "contact-uuid",
      "admin_id": "admin-uuid",
      "workspace_id": "workspace-uuid",
      "event_title": "Product Consultation",
      "event_description": "Initial consultation meeting",
      "start_time": "2025-07-15T09:00:00Z",
      "end_time": "2025-07-15T10:00:00Z",
      "status": "scheduled",
      "location": "Virtual Meeting",
      "notes": "Customer interested in kitchen renovation"
    }
  ]
}
```

- `success` (`get/api/calendar/events.response.200.success`; boolean, optional)
  - example `true`
- `events` (`get/api/calendar/events.response.200.events`; array<object>, optional)
  - `workspace_id` (`get/api/calendar/events.response.200.events.workspace_id`; string, required) — Workspace ID
    - example `"workspace-uuid"`
  - `start_time` (`get/api/calendar/events.response.200.events.start_time`; string, required) — Start time of the appointment
    - format `date-time`; example `"2025-07-15T09:00:00Z"`
  - `end_time` (`get/api/calendar/events.response.200.events.end_time`; string, required) — End time of the appointment
    - format `date-time`; example `"2025-07-15T10:00:00Z"`
  - `id` (`get/api/calendar/events.response.200.events.id`; string, optional) — Unique identifier (for updates)
    - example `"appointment-uuid"`
  - `contact_id` (`get/api/calendar/events.response.200.events.contact_id`; string, optional) — Associated contact ID
    - example `"contact-uuid"`
  - `admin_id` (`get/api/calendar/events.response.200.events.admin_id`; string, optional) — Admin/agent ID
    - example `"admin-uuid"`
  - `event_title` (`get/api/calendar/events.response.200.events.event_title`; string, optional) — Title of the event/appointment
    - example `"Product Consultation"`
  - `event_description` (`get/api/calendar/events.response.200.events.event_description`; string, optional) — Description of the event
    - example `"Initial consultation meeting"`
  - `status` (`get/api/calendar/events.response.200.events.status`; string, optional) — Status of the appointment
    - example `"scheduled"`
  - `location` (`get/api/calendar/events.response.200.events.location`; string, optional) — Location of the appointment
    - example `"Virtual Meeting"`
  - `notes` (`get/api/calendar/events.response.200.events.notes`; string, optional) — Additional notes
    - example `"Customer interested in kitchen renovation"`

### 401

Authentication required

#### Example

```json
{
  "error": "Authentication required",
  "success": false
}
```

- `error` (`get/api/calendar/events.response.401.error`; string, optional)
  - example `"Authentication required"`
- `success` (`get/api/calendar/events.response.401.success`; boolean, optional)
  - example `false`

### 403

Admin privileges required

#### Example

```json
{
  "error": "Admin privileges required",
  "success": false
}
```

- `error` (`get/api/calendar/events.response.403.error`; string, optional)
  - example `"Admin privileges required"`
- `success` (`get/api/calendar/events.response.403.success`; boolean, optional)
  - example `false`

### 500

Internal server error

#### Example

```json
{
  "error": "Internal server error",
  "details": "string",
  "success": false
}
```

- `error` (`get/api/calendar/events.response.500.error`; string, optional)
  - example `"Internal server error"`
- `details` (`get/api/calendar/events.response.500.details`; string, optional)
- `success` (`get/api/calendar/events.response.500.success`; boolean, optional)
  - example `false`


Source: https://developer.channelautomations.com/api/get-api-calendar-events/index.md