# Calendar events

List and retrieve calendar events synced from connected calendar providers.

Retrieve a paginated list of calendar events for the authenticated user. Events are synced from connected calendar providers (Google Calendar, Outlook Calendar, Zoom, Apple Calendar). Results can be filtered by time range, provider, and auto-join status.

#### Query Parameters

**`skip`** integer optional · Defaults to `0`

Number of items to skip for pagination (minimum: 0).

**`limit`** integer optional · Defaults to `50`

Maximum number of items to return (minimum: 1, maximum: 100).

**`start_after`** string optional

Filter events starting after this datetime. ISO 8601 format (e.g., `2026-01-01T00:00:00Z`).

**`start_before`** string optional

Filter events starting before this datetime. ISO 8601 format (e.g., `2026-12-31T23:59:59Z`).

**`provider`** string optional

Filter by calendar provider. Valid values: `google_calendar`, `outlook_calendar`, `zoom`, `apple_calendar`.

**`auto_join_status`** string optional

Filter by auto-join status. Valid values: `pending`, `scheduled`, `joined`, `skipped`, `failed`.

## Returns

Returns a paginated list of calendar event objects with `total` count and `has_more` indicator.

### Calendar Event Object

| Field | Type | Description |
|  --- | --- | --- |
| `id` | string | Unique event ID (`mcevt_` prefix) |
| `calendar_provider` | string | Calendar provider name |
| `title` | string | Event title |
| `start_time` | string | Event start time (ISO 8601) |
| `end_time` | string | Event end time (ISO 8601) |
| `timezone` | string | Event timezone |
| `meeting_link` | string or null | Extracted meeting link (Zoom, Meet, Teams) |
| `meeting_platform` | string or null | Detected platform (`zoom`, `google_meet`, `teams`) |
| `organizer_email` | string or null | Event organizer email |
| `attendee_count` | integer | Number of attendees |
| `is_recurring` | boolean | Whether the event is recurring |
| `status` | string | Event status (`confirmed`, `tentative`, `cancelled`) |
| `auto_join_status` | string | Auto-join status |
| `session_id` | string or null | Linked Meeting Buddy session ID |
| `synced_at` | string | Last sync time (ISO 8601) |
| `created_at` | string | Record creation time (ISO 8601) |


Request

```bash cURL
curl -s -X GET "https://api.aitronos.com/v1/meeting-buddy/calendar/events?limit=20&provider=google_calendar" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | python3 -m json.tool
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

result = client.meeting_buddy.calendar.list_events(
    limit=20,
    provider="google_calendar",
)

for event in result.items:
    print(f"{event.title}: {event.start_time} ({event.auto_join_status})")
print(f"Total: {result.total}")
```


```python Python
import os
import requests

access_token = os.environ["ACCESS_TOKEN"]

url = "https://api.aitronos.com/v1/meeting-buddy/calendar/events"
headers = {"Authorization": f"Bearer {access_token}"}
params = {
    "limit": 20,
    "provider": "google_calendar",
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for event in data["items"]:
    print(f"{event['title']}: {event['start_time']}")
print(f"Total: {data['total']}")
```


```javascript JavaScript
const accessToken = process.env.ACCESS_TOKEN;

const params = new URLSearchParams({
  limit: '20',
  provider: 'google_calendar',
});

const response = await fetch(
  `https://api.aitronos.com/v1/meeting-buddy/calendar/events?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

const data = await response.json();
data.items.forEach(event => {
  console.log(`${event.title}: ${event.start_time}`);
});
console.log(`Total: ${data.total}`);
```

Response

```json 200 OK
{
  "items": [
    {
      "id": "mcevt_abc123def456",
      "calendar_provider": "google_calendar",
      "title": "Team Standup",
      "start_time": "2026-03-03T09:00:00Z",
      "end_time": "2026-03-03T09:30:00Z",
      "timezone": "UTC",
      "meeting_link": "https://meet.google.com/abc-defg-hij",
      "meeting_platform": "google_meet",
      "organizer_email": "manager@example.com",
      "attendee_count": 5,
      "is_recurring": true,
      "status": "confirmed",
      "auto_join_status": "scheduled",
      "session_id": null,
      "synced_at": "2026-03-03T06:00:00Z",
      "created_at": "2026-03-01T12:00:00Z"
    }
  ],
  "total": 1,
  "skip": 0,
  "limit": 20,
  "has_more": false
}
```


```json 401 Unauthorized
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "Authentication is required to access this resource.",
    "type": "client_error",
    "status": 401,
    "details": {},
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-03T10:00:00Z"
  }
}
```

## Get calendar event

Retrieve details for a specific calendar event by its ID.

#### Path Parameters

**`event_id`** string required

The calendar event ID (`mcevt_` prefix).

## Returns

Returns a single [Calendar Event object](#calendar-event-object).

Request

```bash cURL
curl -s -X GET "https://api.aitronos.com/v1/meeting-buddy/calendar/events/mcevt_abc123def456" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | python3 -m json.tool
```


```python Python SDK
from aitronos import Aitronos

client = Aitronos(api_key="your-api-key")

event = client.meeting_buddy.calendar.get_event(
    event_id="mcevt_abc123def456",
)
print(f"{event.title}: {event.start_time}")
```


```python Python
import os
import requests

access_token = os.environ["ACCESS_TOKEN"]
event_id = "mcevt_abc123def456"

url = f"https://api.aitronos.com/v1/meeting-buddy/calendar/events/{event_id}"
headers = {"Authorization": f"Bearer {access_token}"}

response = requests.get(url, headers=headers)
event = response.json()
print(f"{event['title']}: {event['start_time']}")
```


```javascript JavaScript
const accessToken = process.env.ACCESS_TOKEN;
const eventId = 'mcevt_abc123def456';

const response = await fetch(
  `https://api.aitronos.com/v1/meeting-buddy/calendar/events/${eventId}`,
  {
    headers: {
      'Authorization': `Bearer ${accessToken}`,
    },
  }
);

const event = await response.json();
console.log(`${event.title}: ${event.start_time}`);
```

Response

```json 200 OK
{
  "id": "mcevt_abc123def456",
  "calendar_provider": "google_calendar",
  "title": "Team Standup",
  "start_time": "2026-03-03T09:00:00Z",
  "end_time": "2026-03-03T09:30:00Z",
  "timezone": "UTC",
  "meeting_link": "https://meet.google.com/abc-defg-hij",
  "meeting_platform": "google_meet",
  "organizer_email": "manager@example.com",
  "attendee_count": 5,
  "is_recurring": true,
  "status": "confirmed",
  "auto_join_status": "scheduled",
  "session_id": null,
  "synced_at": "2026-03-03T06:00:00Z",
  "created_at": "2026-03-01T12:00:00Z"
}
```


```json 404 Not Found
{
  "success": false,
  "error": {
    "code": "CALENDAR_EVENT_NOT_FOUND",
    "message": "The requested calendar event could not be found.",
    "system_message": "Calendar event not found",
    "type": "client_error",
    "status": 404,
    "details": {
      "event_id": "mcevt_nonexistent"
    },
    "trace_id": "abc-123-def",
    "timestamp": "2026-03-03T10:00:00Z"
  }
}
```

## Related Resources

- [Calendar Sync](/docs/api-reference/meeting-buddy/calendar-sync)
- [Calendar Connections](/docs/api-reference/meeting-buddy/calendar-connections)
- [Auto-Join Rules](/docs/api-reference/meeting-buddy/auto-join-rules)
- [Start Session](/docs/api-reference/meeting-buddy/start-session)
- [List Sessions](/docs/api-reference/meeting-buddy/list-sessions)