---
title: "List Calendar Events"
method: GET
path: "/v2.0/calendar"
tags: ["Calendar V2 API"]
---

# List Calendar Events

`GET /v2.0/calendar`

Returns a page of calendar entries (Tasks and Appointments) for the caller, optionally filtered by leadId, type and completion status.

Notes:
- At least one of startTime or endTime is required; requests missing both return 400 INVALID_PARAMETER.
- includeFinished=true returns both finished and unfinished entries; includeFinished=false returns only unfinished.
- Results are wrapped under the 'data' key, which also carries pagination metadata.

## Query parameters

- `leadId` string — Lead ID (optional, filter by specific lead)
- `startTime` string — Start time, ISO 8601 with offset. At least one of startTime or endTime is required.
- `endTime` string — End time, ISO 8601 with offset. At least one of startTime or endTime is required.
- `startTimeMs` string — Start time as Unix timestamp in milliseconds. Used when startTime is not provided.
- `endTimeMs` string — End time as Unix timestamp in milliseconds. Used when endTime is not provided.
- `timeZoneCode` string — Timezone code (IANA format, e.g., America/Los_Angeles)
- `includeFinished` string — Include finished calendars
- `page` string — Page number (starts from 0)
- `pageSize` string — Page size (max 500)
- `sort` string — Sort field (e.g., startTime)
- `desc` string — Sort in descending order
- `sourceType` string — Filter by source type codes. Multiple values allowed.

## Headers

- `Authorization` string, required

## Response `200`

Page of calendar entries with pagination metadata.

- CalendarListResponseEnvelope — Response envelope for GET /v2.0/calendar. Wraps the paginated calendar list under the 'data' field.
  - `data` CalendarListResponseV2 — Calendar list response with pagination
    - `total` integer — Total count of calendars matching the query
    - `page` integer — Current page number (starts from 0)
    - `pageSize` integer — Page size
    - `items` CalendarItemV2[] — List of calendar items
      - `id` string — Calendar ID with type suffix (e.g., '12345-task' or '12345-appointment')
      - `type` string — Calendar type for identification only (TASK or APPOINTMENT)
      - `taskId` integer — Task ID associated with the calendar item
      - `sourceType` integer — Source type code from calendar system
      - `content` string — Event content/description
      - `title` string — Event title (auto-generated from lead name + event type)
      - `finished` boolean — Whether the calendar item is finished
      - `startAt` string — Start time in ISO8601 format
      - `endAt` string — End time in ISO8601 format
      - `startAtMs` integer — Start time as Unix timestamp in milliseconds
      - `endAtMs` integer — End time as Unix timestamp in milliseconds
      - `timeZoneCode` string — Timezone code
      - `leadId` integer — Lead ID

## Other responses

- `400` — Invalid parameters (20012 INVALID_PARAMETER).
- `401` — Missing or invalid authentication token.
- `500` — Internal server error.

---

[API](https://skmtc.net/lofty/apis/lofty-service-open-apis.md) · [All operations](https://skmtc.net/lofty/apis/lofty-service-open-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lofty/lofty-service-open-apis/versions/23e640467118/schema)