---
title: "Query events from connected calendar accounts"
method: POST
path: "/open/v1/calendar/event/query"
---

# Query events from connected calendar accounts

`POST /open/v1/calendar/event/query`

## Request

- Base URL: `https://ticktick.com`
- URL: `https://ticktick.com/open/v1/calendar/event/query`
- Auth: none declared

Query events from one account selected by required `accountId` and a non-empty `calendarIds`
list obtained from the calendar list endpoint. Hidden, unsupported, or foreign calendars are rejected. When no
time range is supplied, the range is now through the following three months. A query range may
not exceed three months. Recurring events depend on whether the calendar provider returns
expanded occurrences; a recurring series that starts outside the range may be omitted even if
it has occurrences inside the range. `status` is `complete`, `partial`, or `failed`.
`accountErrors` gives stable failure codes per account; `errorAccountIds` remains for compatibility.
HTTP 200 with `failed` means the selected account could not be queried.
An unknown or inaccessible account returns 404.

## Request body

- CalendarEventQuery
  - `accountId` string, required: Required connected calendar account ID.
  - `calendarIds` string[], required: Required non-blank local calendar IDs belonging to the account and returned by the calendar list endpoint.
  - `begin` string: Accepts the TickTick timestamp format, e.g. "2026-09-24T10:00:00.000+0800", or an ISO 8601 timestamp with offset.
  - `end` string: Accepts the TickTick timestamp format, e.g. "2026-09-24T10:00:00.000+0800", or an ISO 8601 timestamp with offset.

## Response `200`

Events and any accounts that could not be queried.

- CalendarEventQueryResult
  - `status` 'complete' | 'partial' | 'failed'
  - `accountErrors` CalendarAccountError[]
    - `accountId` string
    - `errorCode` 'calendar_account_reauth_required' | 'calendar_provider_unavailable'
    - `retryable` boolean
  - `begin` string: Resolved query start in "yyyy-MM-dd'T'HH:mm:ss.SSSZ" format (e.g. "2026-09-24T10:00:00.000+0800").
  - `end` string: Resolved query end in "yyyy-MM-dd'T'HH:mm:ss.SSSZ" format (e.g. "2026-09-24T10:00:00.000+0800").
  - `events` CalendarEvent[]
    - `accountId` string
    - `calendarId` string
    - `calendarName` string
    - `id` string
    - `uid` string: Provider event UID, when available.
    - `title` string
    - `content` string
    - `timeZone` string
    - `startTime` string: Event start in "yyyy-MM-dd'T'HH:mm:ss.SSSZ" format (e.g. "2026-09-24T10:00:00.000+0800").
    - `endTime` string: Event end in "yyyy-MM-dd'T'HH:mm:ss.SSSZ" format (e.g. "2026-09-24T10:00:00.000+0800").
    - `isAllDay` boolean
    - `location` string
    - `repeatFlag` string
    - `recurrence` string: Provider recurrence data, when available.
    - `originalStartTime` string: Original start time of a changed recurring occurrence, when available, in "yyyy-MM-dd'T'HH:mm:ss.SSSZ" format (e.g. "2026-09-24T10:00:00.000+0800").
    - `exDates` string[]: Excluded occurrence dates, when available.
  - `errorAccountIds` string[]: Accounts that could not be queried; events from other accounts are still returned.

## Other responses

- `400`: Invalid range (`invalid_calendar_range` or `calendar_invalid_time_range`), missing account (`calendar_account_id_required`), missing calendar IDs (`calendar_ids_required`), invalid selection (`calendar_not_queryable`), or malformed request.
- `404`: Selected calendar account does not exist or is inaccessible (`calendar_account_not_found`).

## Changes

- **2026-11-13** `bbd09df38f88`: 3 breaking
  - added the new required request property `calendarIds`
  - request body became required
  - the request property `accountId` became required
- **2026-10-14** `560e790aecb3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/ticktick/apis/ticktick-openapi/changes/open/v1/calendar/event/query/post.md)

---

[API](https://skmtc.dev/ticktick/apis/ticktick-openapi.md) - [All operations](https://skmtc.dev/ticktick/apis/ticktick-openapi/llms.txt) - [OpenAPI document](https://skmtc.dev/ticktick/apis/ticktick-openapi/revisions/bbd09df38f88?raw)