> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # QueryEvents # Package: marketingPlan # Namespace: CalendarService # Method link: https://dev.wix.com/docs/api-reference/business-management/marketing/marketing-plan/calendar-event-v1/query-events.md ## Permission Scopes: Manage Marketing Plans: SCOPE.PROMOTE.MANAGE-MARKETING-PLAN ## Introduction Retrieves events that occur within a given date range. The request must include a date range filter with both `filter.date.$gte` (start, inclusive) and `filter.date.$lte` (end, inclusive). Omitting either field returns an `INVALID_ARGUMENT` error. Only this date filter is honored: any `sort`, `paging`, `cursorPaging`, `fields`, or `fieldsets` in the request are ignored. Results are always sorted by date in ascending order, and the response is capped at 100 events with no cursor or paging (narrow the date range to stay within the cap). Results include one-time events, the individual occurrences of recurring events that fall within the range, and read-only events from the site's connected calendars (such as Google Calendar). --- ## REST API ### Schema ``` Method: queryEvents Description: Retrieves events that occur within a given date range. The request must include a date range filter with both `filter.date.$gte` (start, inclusive) and `filter.date.$lte` (end, inclusive). Omitting either field returns an `INVALID_ARGUMENT` error. Only this date filter is honored: any `sort`, `paging`, `cursorPaging`, `fields`, or `fieldsets` in the request are ignored. Results are always sorted by date in ascending order, and the response is capped at 100 events with no cursor or paging (narrow the date range to stay within the cap). Results include one-time events, the individual occurrences of recurring events that fall within the range, and read-only events from the site's connected calendars (such as Google Calendar). URL: https://www.wixapis.com/promote/marketing-plan-service/v1/events/query Method: POST Method parameters: param name: query | type: QueryV2 - ONE-OF: - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. | validation: minimum 0, maximum 100, format int32 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. | validation: maxLength 16000 - name: filter | type: object | description: Filter object. Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-filter-section). - name: sort | type: array | description: Sort object. Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-sort-section). | validation: maxItems 5 - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: fields | type: array | description: Array of projected fields. A list of specific field names to return. If `fieldsets` are also specified, the union of `fieldsets` and `fields` is returned. | validation: maxItems 5, maxLength 200 - name: fieldsets | type: array | description: Array of named, predefined sets of projected fields. A array of predefined named sets of fields to be returned. Specifying multiple `fieldsets` will return the union of fields from all sets. If `fields` are also specified, the union of `fieldsets` and `fields` is returned. | validation: maxItems 5, maxLength 200 Return type: QueryEventsResponse - name: events | type: array | description: List of events (and recurring occurrences) that fall within the requested date range. | validation: minItems 0, maxItems 100 - name: id | type: string | description: Unique event GUID. Assigned on creation. | validation: format GUID - name: name | type: string | description: Display name of the event (for example, "Summer Sale" or "Independence Day"). | validation: maxLength 3000 - name: date | type: string | description: Date and time of the event. Set this field for a one-time event. For a recurring event, set `recurringRule` instead. If both are sent, `recurringRule` takes precedence and `date` is ignored. If neither is sent, the request fails with `INVALID_ARGUMENT`. | validation: format date-time - name: calendarId | type: string | description: GUID of the marketing calendar this event belongs to. | validation: format GUID - name: recurringRule | type: RecurringRule | description: Recurrence rule for the event. Set this field for a recurring event (weekly, monthly, or yearly). If both `recurringRule` and `date` are sent, `recurringRule` takes precedence and `date` is ignored. `frequency` is required and must not be `UNKNOWN`; omitting it returns a `FAILED_PRECONDITION` error. - name: frequency | type: Frequency | description: How often the event repeats. - enum: - WEEKLY: The event repeats every week. - MONTHLY: The event repeats every month. - YEARLY: The event repeats every year. - name: weekDay | type: integer | description: Day of the week the event falls on, where `0` is Monday and `6` is Sunday. Used with `WEEKLY` frequency. | validation: minimum 0, maximum 6, format int32 - name: monthDay | type: integer | description: Day of the month the event falls on. Used with `MONTHLY` frequency. | validation: minimum 1, maximum 31, format int32 - name: month | type: integer | description: Month of the year the event falls in, where `1` is January and `12` is December. Used with `YEARLY` frequency. | validation: minimum 1, maximum 12, format int32 - name: occurrencePosition | type: integer | description: Ordinal position of the occurrence within the period (for example, `2` means "the 2nd Monday of the month"). Used with `MONTHLY` frequency alongside `weekDay`. | validation: minimum 1, maximum 5, format int32 - name: startDate | type: string | description: Date from which the recurrence starts. | validation: format date-time - name: recurringOccurrences | type: array | description: Computed individual occurrences of a recurring event. Read-only; populated only in `QueryEvents` responses, and only for occurrences within the requested date range. | validation: minItems 0, maxItems 100 - name: date | type: string | description: Date and time of this occurrence. | validation: format date-time - name: description | type: string | description: Optional description providing additional context about the event. | validation: maxLength 3000 ``` ### Examples ### Query events in a date range Retrieve calendar events that fall within a date range. The only honored filter is a date range using $gte and $lte. ```curl curl -X POST \ 'https://www.wixapis.com/promote/marketing-plan-service/v1/events/query' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{ "query": { "filter": { "date": { "$gte": "2026-07-01T00:00:00.000Z", "$lte": "2026-07-31T23:59:59.999Z" } } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.promoteGrowthToolsMarketingPlan.calendarEvents.queryEvents(options) Description: Retrieves events that occur within a given date range. The request must include a date range filter with both `filter.date.$gte` (start, inclusive) and `filter.date.$lte` (end, inclusive). Omitting either field returns an `INVALID_ARGUMENT` error. Only this date filter is honored: any `sort`, `paging`, `cursorPaging`, `fields`, or `fieldsets` in the request are ignored. Results are always sorted by date in ascending order, and the response is capped at 100 events with no cursor or paging (narrow the date range to stay within the cap). Results include one-time events, the individual occurrences of recurring events that fall within the range, and read-only events from the site's connected calendars (such as Google Calendar). Method parameters: param name: options | type: QueryEventsOptions none - name: query | type: QueryV2 | description: Query options. Only the date range filter (`filter.date.$gte` and `filter.date.$lte`) is honored. Any `sort`, `paging`, `cursorPaging`, `fields`, or `fieldsets` values are ignored. - ONE-OF: - name: paging | type: Paging | description: Paging options to limit and skip the number of items. - name: limit | type: integer | description: Number of items to load. | validation: minimum 0, format int32 - name: offset | type: integer | description: Number of items to skip in the current sort order. | validation: minimum 0, format int32 - name: cursorPaging | type: CursorPaging | description: Cursor token pointing to a page of results. Not used in the first request. Following requests use the cursor token and not `filter` or `sort`. - name: limit | type: integer | description: Maximum number of items to return in the results. | validation: minimum 0, maximum 100, format int32 - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. Pass the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. | validation: maxLength 16000 - name: filter | type: object | description: Filter object. Learn more about the [filter section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-filter-section). - name: sort | type: array | description: Sort object. Learn more about the [sort section](https://dev.wix.com/docs/rest/articles/getting-started/api-query-language.md#the-sort-section). | validation: maxItems 5 - name: fieldName | type: string | description: Name of the field to sort by. | validation: maxLength 512 - name: order | type: SortOrder | description: Sort order. - enum: ASC, DESC - name: fields | type: array | description: Array of projected fields. A list of specific field names to return. If `fieldsets` are also specified, the union of `fieldsets` and `fields` is returned. | validation: maxItems 5, maxLength 200 - name: fieldsets | type: array | description: Array of named, predefined sets of projected fields. A array of predefined named sets of fields to be returned. Specifying multiple `fieldsets` will return the union of fields from all sets. If `fields` are also specified, the union of `fieldsets` and `fields` is returned. | validation: maxItems 5, maxLength 200 Return type: PROMISE - name: events | type: array | description: List of events (and recurring occurrences) that fall within the requested date range. | validation: minItems 0, maxItems 100 - name: _id | type: string | description: Unique event GUID. Assigned on creation. | validation: format GUID - name: name | type: string | description: Display name of the event (for example, "Summer Sale" or "Independence Day"). | validation: maxLength 3000 - name: date | type: Date | description: Date and time of the event. Set this field for a one-time event. For a recurring event, set `recurringRule` instead. If both are sent, `recurringRule` takes precedence and `date` is ignored. If neither is sent, the request fails with `INVALID_ARGUMENT`. - name: calendarId | type: string | description: GUID of the marketing calendar this event belongs to. | validation: format GUID - name: recurringRule | type: RecurringRule | description: Recurrence rule for the event. Set this field for a recurring event (weekly, monthly, or yearly). If both `recurringRule` and `date` are sent, `recurringRule` takes precedence and `date` is ignored. `frequency` is required and must not be `UNKNOWN`; omitting it returns a `FAILED_PRECONDITION` error. - name: frequency | type: Frequency | description: How often the event repeats. - enum: - WEEKLY: The event repeats every week. - MONTHLY: The event repeats every month. - YEARLY: The event repeats every year. - name: weekDay | type: integer | description: Day of the week the event falls on, where `0` is Monday and `6` is Sunday. Used with `WEEKLY` frequency. | validation: minimum 0, maximum 6, format int32 - name: monthDay | type: integer | description: Day of the month the event falls on. Used with `MONTHLY` frequency. | validation: minimum 1, maximum 31, format int32 - name: month | type: integer | description: Month of the year the event falls in, where `1` is January and `12` is December. Used with `YEARLY` frequency. | validation: minimum 1, maximum 12, format int32 - name: occurrencePosition | type: integer | description: Ordinal position of the occurrence within the period (for example, `2` means "the 2nd Monday of the month"). Used with `MONTHLY` frequency alongside `weekDay`. | validation: minimum 1, maximum 5, format int32 - name: startDate | type: Date | description: Date from which the recurrence starts. - name: recurringOccurrences | type: array | description: Computed individual occurrences of a recurring event. Read-only; populated only in `QueryEvents` responses, and only for occurrences within the requested date range. | validation: minItems 0, maxItems 100 - name: date | type: Date | description: Date and time of this occurrence. - name: description | type: string | description: Optional description providing additional context about the event. | validation: maxLength 3000 ``` ### Examples ### Query events in a date range ```javascript import { calendarEvents } from "@wix/promote-growth-tools-marketing-plan"; const query = { filter: { date: { $gte: "2026-07-01T00:00:00.000Z", $lte: "2026-07-31T23:59:59.999Z", }, }, }; async function queryEvents() { const response = await calendarEvents.queryEvents({ query }); } /* Promise resolves to: * { * "events": [ * { * "_id": "d7a341c4-196b-46e7-813c-2b0fc1847ec6", * "name": "Summer Sale Launch", * "description": "Kick off our summer promotion across all social channels.", * "date": "2026-07-01T09:00:00.000Z" * } * ] * } */ ``` ### queryEvents (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { calendarEvents } from '@wix/promote-growth-tools-marketing-plan'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { calendarEvents }, // Include the auth strategy and host as relevant }); async function queryEvents(options) { const response = await myWixClient.calendarEvents.queryEvents(options); }; ``` ---