> ## Documentation Index
> Fetch the complete documentation index at: https://discord-platform-username.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Guild Scheduled Event
> Reference for Discord scheduled event objects and management endpoints.
export const Route = ({method, children}) => {
return
{method}
{children}
;
};
export const ManualAnchor = ({id}) => {
return ;
};
A representation of a scheduled event in a [guild](/developers/resources/guild).
### Guild Scheduled Event Object
###### Guild Scheduled Event Structure
| Field | Type | Description |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | snowflake | the id of the scheduled event |
| guild\_id | snowflake | the guild id which the scheduled event belongs to |
| channel\_id \*\* | ?snowflake | the channel id in which the scheduled event will be hosted, or `null` if [scheduled entity type](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-types) is `EXTERNAL` |
| creator\_id? \* | ?snowflake | the id of the user that created the scheduled event \* |
| name | string | the name of the scheduled event (1-100 characters) |
| description? | ?string | the description of the scheduled event (1-1000 characters) |
| scheduled\_start\_time | ISO8601 timestamp | the time the scheduled event will start |
| scheduled\_end\_time \*\* | ?ISO8601 timestamp | the time the scheduled event will end, required if entity\_type is `EXTERNAL` |
| privacy\_level | [privacy level](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-privacy-level) | the privacy level of the scheduled event |
| status | [event status](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-status) | the status of the scheduled event |
| entity\_type | [scheduled entity type](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-types) | the type of the scheduled event |
| entity\_id | ?snowflake | the id of an entity associated with a guild scheduled event |
| entity\_metadata \*\* | ?[entity metadata](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata) | additional metadata for the guild scheduled event |
| creator? | [user](/developers/resources/user#user-object) object | the user that created the scheduled event |
| user\_count? | integer | the number of users subscribed to the scheduled event |
| image? | ?string | the [cover image hash](/developers/reference#image-formatting) of the scheduled event |
| recurrence\_rule | ?[recurrence rule](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object) | the definition for how often this event should recur |
\* `creator_id` will be null and `creator` will not be included for events created before October 25th, 2021, when the concept of `creator_id` was introduced and tracked.
\*\* See [field requirements by entity type](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-field-requirements-by-entity-type) to understand the relationship between `entity_type` and the following fields: `channel_id`, `entity_metadata`, and `scheduled_end_time`
###### Guild Scheduled Event Privacy Level
| Level | Value | Description |
| ----------- | ----- | ------------------------------------------------------- |
| GUILD\_ONLY | 2 | the scheduled event is only accessible to guild members |
###### Guild Scheduled Event Entity Types
| Type | Value |
| --------------- | ----- |
| STAGE\_INSTANCE | 1 |
| VOICE | 2 |
| EXTERNAL | 3 |
###### Field Requirements By Entity Type
The following table shows field requirements based on current entity type.
`value` : This field is required to be a non-null value
`null` : This field is required to be null
`-` : No strict requirements
| Entity Type | channel\_id | entity\_metadata | scheduled\_end\_time |
| --------------- | ----------- | ---------------- | -------------------- |
| STAGE\_INSTANCE | value | null | - |
| VOICE | value | null | - |
| EXTERNAL | null | value \* | value |
\* `entity_metadata` with a non-null `location` must be provided
###### Guild Scheduled Event Status
| Type | Value |
| ------------ | ----- |
| SCHEDULED | 1 |
| ACTIVE | 2 |
| COMPLETED \* | 3 |
| CANCELED \* | 4 |
\* Once `status` is set to `COMPLETED` or `CANCELED`, the `status` can no longer be updated
###### Valid Guild Scheduled Event Status Transitions
SCHEDULED --> ACTIVE
ACTIVE --------> COMPLETED
SCHEDULED --> CANCELED
###### Guild Scheduled Event Entity Metadata
| Field | Type | Description |
| ------------ | ------ | ---------------------------------------- |
| location? \* | string | location of the event (1-100 characters) |
\* [required](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata) for events with `'entity_type': EXTERNAL`
### Guild Scheduled Event User Object
###### Guild Scheduled Event User Structure
| Field | Type | Description |
| --------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| guild\_scheduled\_event\_id | snowflake | the scheduled event id which the user subscribed to |
| user | [user](/developers/resources/user#user-object) | user which subscribed to an event |
| member? | [guild member](/developers/resources/guild#guild-member-object) | guild member data for this user for the guild which this event belongs to, if any |
### Guild Scheduled Event Recurrence Rule Object
Discord's recurrence rule is a subset of the behaviors [defined in the iCalendar RFC](https://datatracker.ietf.org/doc/html/rfc5545) and implemented by [python's dateutil rrule](https://dateutil.readthedocs.io/en/stable/rrule.html)
There are currently many limitations to this system. Please see "System limitations" below
###### Guild Scheduled Event Recurrence Rule Structure
| Field | Type | Description |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| start | ISO8601 timestamp | Starting time of the recurrence interval |
| end \[1] | ?ISO8601 timestamp | Ending time of the recurrence interval |
| frequency | [recurrence rule - frequency](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-frequency) object | How often the event occurs |
| interval | int | The spacing between the events, defined by `frequency`. For example, `frequency` of `WEEKLY` and an `interval` of `2` would be "every-other week" |
| by\_weekday | ?array of [recurrence rule - weekday](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-weekday) | Set of specific days within a week for the event to recur on |
| by\_n\_weekday | ?array of [recurrence rule - n\_weekday](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-nweekday-structure) objects | List of specific days within a specific week (1-5) to recur on |
| by\_month | ?array of [recurrence rule - month](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-month) | Set of specific months to recur on |
| by\_month\_day | ?array of int | Set of specific dates within a month to recur on |
| by\_year\_day \[1] | ?array of int | Set of days within a year to recur on (1-364) |
| count \[1] | ?int | The total amount of times that the event is allowed to recur before stopping |
\[1] - Cannot be set externally currently.
The current system limitations are present due to how reoccurring event data needs to be displayed in the client.
In the future, we would like to open the system up to have fewer / none of these restrictions.
###### The following fields cannot be set by the client / application
* `count`
* `end`
* `by_year_day`
###### The following combinations are mutually exclusive
* `by_weekday`
* `by_n_weekday`
* `by_month` + `by_month_day`
###### `by_weekday`
* Only valid for daily and weekly events (`frequency` of `DAILY` (`0`) or `WEEKLY` (`1`))
* when used in a daily event (`frequency` is `DAILY` (`0`))
* The values present in the `by_weekday` event must be a "known set" of weekdays.
* The following are current allowed "sets"
* Monday - Friday (`[0, 1, 2, 3, 4]`)
* Tuesday - Saturday (`[1, 2, 3, 4, 5]`)
* Sunday - Thursday (`[6, 0, 1, 2, 3]`)
* Friday & Saturday (`[4, 5]`)
* Saturday & Sunday (`[5, 6]`)
* Sunday & Monday (`[6, 0]`)
* when used in a weekly event (`frequency` is `WEEKLY` (`1`))
* `by_weekday` array currently can only be a length of `1`
* i.e: You can only select a single day within a week to have a recurring event on
* If you wish to have multiple days within a week have a recurring event, please use a `frequency` of `DAILY`
* Also, see `interval` below for "every-other" week information
###### `by_n_weekday`
* Only valid for monthly events (`frequency` of `MONTHLY` (`1`))
* `by_n_weekday` array currently can only be a length of `1`
* i.e: You can only select a single day within a month to have a recurring event on
###### `by_month` and `by_month_day`
* Only valid for annual event (`frequency` is `YEARLY` (`0`))
* both `by_month` and `by_month_day` must be provided
* both `by_month` and `by_month_day` arrays must have a length of `1`
* (i.e: You can only set a single date for annual events)
###### `interval` can only be set to a value other than `1` when `frequency` is set to `WEEKLY` (`1`)
* In this situation, interval can be set to `2`
* This allowance enables "every-other week" events
* Due to the limitations placed on `by_weekday` this means that if you wish to use "every-other week" functionality
you can only do so for a single day.
**Every weekday**
```js theme={null}
frequency = 3 // Frequency.DAILY
interval = 1
by_weekday = [0, 1, 2, 3, 4] // [Weekday.MONDAY, ..., Weekday.FRIDAY]
```
**Every Wednesday**
```js theme={null}
frequency = 2 // Frequency.WEEKLY
interval = 1
by_weekday = [2] // [Weekday.WEDNESDAY]
```
**Every other Wednesday**
```js theme={null}
frequency = 2 // Frequency.WEEKLY
interval = 2
by_weekday = [2] // [Weekday.WEDNESDAY]
```
**Monthly on the fourth Wednesday**
```js theme={null}
frequency = 1 // Frequency.MONTHLY
interval = 1
by_n_weekday = [{
n: 4,
day: 2 // Weekday.WEDNESDAY
}]
```
**Annually on July 24**
```js theme={null}
frequency = 0 // Frequency.YEARLY
interval = 1
by_month = [7] // [Month.JULY]
by_month_day = [24]
```
###### Guild Scheduled Event Recurrence Rule - Frequency
| Type | Value |
| ------- | ----- |
| YEARLY | 0 |
| MONTHLY | 1 |
| WEEKLY | 2 |
| DAILY | 3 |
###### Guild Scheduled Event Recurrence Rule - Weekday
| Type | Value |
| --------- | ----- |
| MONDAY | 0 |
| TUESDAY | 1 |
| WEDNESDAY | 2 |
| THURSDAY | 3 |
| FRIDAY | 4 |
| SATURDAY | 5 |
| SUNDAY | 6 |
###### Guild Scheduled Event Recurrence Rule - N\_Weekday Structure
| Field | Type | Description | | |
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | - | --------------------------------------------------------------------------------- |
| n | int | The week to reoccur on. 1 - 5 | | |
| day | [recurrence rule - weekday](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object-guild-scheduled-event-recurrence-rule-weekday) | The day within the week to reoccur on | | guild member data for this user for the guild which this event belongs to, if any |
###### Guild Scheduled Event Recurrence Rule - Month
| Type | Value |
| --------- | ----- |
| JANUARY | 1 |
| FEBRUARY | 2 |
| MARCH | 3 |
| APRIL | 4 |
| MAY | 5 |
| JUNE | 6 |
| JULY | 7 |
| AUGUST | 8 |
| SEPTEMBER | 9 |
| OCTOBER | 10 |
| NOVEMBER | 11 |
| DECEMBER | 12 |
## List Scheduled Events for Guild
/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/scheduled-events
Returns a list of [guild scheduled event](/developers/resources/guild-scheduled-event#guild-scheduled-event-object) objects for the given guild.
###### Query String Params
| Field | Type | Description |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------ |
| with\_user\_count? | [boolean](/developers/reference#boolean-query-strings) | include number of users subscribed to each event |
## Create Guild Scheduled Event
/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/scheduled-events
Create a guild scheduled event in the guild. Returns a [guild scheduled event](/developers/resources/guild-scheduled-event#guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Create](/developers/events/gateway-events#guild-scheduled-event-create) Gateway event.
A guild can have a maximum of 100 events with `SCHEDULED` or `ACTIVE` status at any time.
This endpoint supports the `X-Audit-Log-Reason` header.
###### JSON Params
| Field | Type | Description |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| channel\_id? \* | snowflake \* | the channel id of the scheduled event. |
| entity\_metadata? \*\* | [entity metadata](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata) | the entity metadata of the scheduled event |
| name | string | the name of the scheduled event |
| privacy\_level | [privacy level](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-privacy-level) | the privacy level of the scheduled event |
| scheduled\_start\_time | ISO8601 timestamp | the time to schedule the scheduled event |
| scheduled\_end\_time? \*\* | ISO8601 timestamp | the time when the scheduled event is scheduled to end |
| description? | string | the description of the scheduled event |
| entity\_type | [entity type](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-types) | the entity type of the scheduled event |
| image? | [image data](/developers/reference#image-data) | the cover image of the scheduled event |
| recurrence\_rule? | [recurrence rule](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object) | the definition for how often this event should recur |
\* Optional for events with `'entity_type': EXTERNAL`
\*\* Required for events with `'entity_type': EXTERNAL`
## Get Guild Scheduled Event
/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/scheduled-events/[\{guild\_scheduled\_event.id}](/developers/resources/guild-scheduled-event#guild-scheduled-event-object)
Get a guild scheduled event. Returns a [guild scheduled event](/developers/resources/guild-scheduled-event#guild-scheduled-event-object) object on success.
###### Query String Params
| Field | Type | Description |
| ------------------ | ------------------------------------------------------ | ------------------------------------------------ |
| with\_user\_count? | [boolean](/developers/reference#boolean-query-strings) | include number of users subscribed to this event |
## Modify Guild Scheduled Event
/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/scheduled-events/[\{guild\_scheduled\_event.id}](/developers/resources/guild-scheduled-event#guild-scheduled-event-object)
Modify a guild scheduled event. Returns the modified [guild scheduled event](/developers/resources/guild-scheduled-event#guild-scheduled-event-object) object on success. Fires a [Guild Scheduled Event Update](/developers/events/gateway-events#guild-scheduled-event-update) Gateway event.
To start or end an event, use this endpoint to modify the event's [status](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-status) field.
This endpoint supports the `X-Audit-Log-Reason` header.
This endpoint silently discards `entity_metadata` for non-`EXTERNAL` events.
All parameters to this endpoint are optional.
###### JSON Params
| Field | Type | Description |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| channel\_id? \* | ?snowflake | the channel id of the scheduled event, set to `null` if changing entity type to `EXTERNAL` |
| entity\_metadata? | ?[entity metadata](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-metadata) | the entity metadata of the scheduled event |
| name? | string | the name of the scheduled event |
| privacy\_level? | [privacy level](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-privacy-level) | the privacy level of the scheduled event |
| scheduled\_start\_time? | ISO8601 timestamp | the time to schedule the scheduled event |
| scheduled\_end\_time? \* | ISO8601 timestamp | the time when the scheduled event is scheduled to end |
| description? | ?string | the description of the scheduled event |
| entity\_type? \* | [event entity type](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-entity-types) | the entity type of the scheduled event |
| status? | [event status](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-guild-scheduled-event-status) | the status of the scheduled event |
| image? | [image data](/developers/reference#image-data) | the cover image of the scheduled event |
| recurrence\_rule? | ?[recurrence rule](/developers/resources/guild-scheduled-event#guild-scheduled-event-recurrence-rule-object) | the definition for how often this event should recur |
\* If updating `entity_type` to `EXTERNAL`:
* `channel_id` is required and [must be set to null](/developers/resources/guild-scheduled-event#guild-scheduled-event-object-field-requirements-by-entity-type)
* `entity_metadata` with a `location` field must be provided
* `scheduled_end_time` must be provided
## Delete Guild Scheduled Event
/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/scheduled-events/[\{guild\_scheduled\_event.id}](/developers/resources/guild-scheduled-event#guild-scheduled-event-object)
Delete a guild scheduled event. Returns a `204` on success. Fires a [Guild Scheduled Event Delete](/developers/events/gateway-events#guild-scheduled-event-delete) Gateway event.
## Get Guild Scheduled Event Users
/guilds/[\{guild.id}](/developers/resources/guild#guild-object)/scheduled-events/[\{guild\_scheduled\_event.id}](/developers/resources/guild-scheduled-event#guild-scheduled-event-object)/users
Get a list of guild scheduled event users subscribed to a guild scheduled event. Returns a list of [guild scheduled event user](/developers/resources/guild-scheduled-event#guild-scheduled-event-user-object) objects on success. Guild member data, if it exists, is included if the `with_member` query parameter is set.
###### Query String Params
| Field | Type | Description | Default |
| ------------- | ------------------------------------------------------ | --------------------------------------------- | ------- |
| limit? | number | number of users to return (up to maximum 100) | 100 |
| with\_member? | [boolean](/developers/reference#boolean-query-strings) | include guild member data if it exists | false |
| before? \* | snowflake | consider only users before given user id | null |
| after? \* | snowflake | consider only users after given user id | null |
\* Provide a user id to `before` and `after` for pagination. Users will always be returned in ascending order by `user_id`. If both `before` and `after` are provided, only `before` is respected. Fetching users in-between `before` and `after` is not supported.
## Guild Scheduled Event Status Update Automation
NOTE: `status` and `entity_type` here are expressed by name rather than their value for readability
### An active scheduled event for a stage channel where all users have left the stage channel will automatically end a few minutes after the last user leaves the channel
When an event with `'status': ACTIVE` and `'entity_type': STAGE_INSTANCE` has no users connected to the stage channel for a certain period of time (on the order of minutes), the event `status` will be automatically set to `COMPLETED`.
### An active scheduled event for a voice channel where all users have left the voice channel will automatically end a few minutes after the last user leaves the channel
When an event with `'status': ACTIVE` and `'entity_type': VOICE` has no users connected to the voice channel for a certain period of time (on the order of minutes), the event `status` will be automatically set to `COMPLETED`.
### An external event will automatically begin at its scheduled start time
An event with `'entity_type': EXTERNAL` at its `scheduled_start_time` will automatically have `status` set to `ACTIVE`.
### An external event will automatically end at its scheduled end time
An event with `'entity_type': EXTERNAL` at its `scheduled_end_time` will automatically have `status` set to `COMPLETED`.
### Any scheduled event which has not begun after its scheduled start time will be automatically cancelled after a few hours
Any event with `'status': SCHEDULED` after a certain time interval (on the order of hours) beyond its `scheduled_start_time` will have its `status` automatically set to `CANCELLED`.
## Guild Scheduled Event Permissions Requirements
NOTE: `entity_type` is expressed by name rather than value for readability
A user must be a member of the guild in order to access events for that guild unless the guild is public. If a guild is public, events in that guild may be visible depending on the event type and the permissions of any channels associated with the event.
### Permissions for events with entity\_type: STAGE\_INSTANCE
The computed permissions for the user in the `channel_id` associated with the event must include:
#### Get Permissions
* `VIEW_CHANNEL`
#### Create Permissions
* `CREATE_EVENTS`
* `MANAGE_CHANNELS`
* `MUTE_MEMBERS`
* `MOVE_MEMBERS`
#### Modify/Delete Permissions
* If the event was created by the current user, either `CREATE_EVENTS` or `MANAGE_EVENTS`. Otherwise, `MANAGE_EVENTS`
* `MANAGE_CHANNELS`
* `MUTE_MEMBERS`
* `MOVE_MEMBERS`
### Permissions for events with entity\_type: VOICE
The computed permissions for the user in the `channel_id` associated with the event must include:
#### Get Permissions
* `VIEW_CHANNEL`
#### Create permissions
* `CREATE_EVENTS`
* `VIEW_CHANNEL`
* `CONNECT`
#### Modify/Delete Permissions
* If the event was created by the current user, either `CREATE_EVENTS` or `MANAGE_EVENTS`. Otherwise, `MANAGE_EVENTS`
* `VIEW_CHANNEL`
* `CONNECT`
### Permissions for events with entity\_type: EXTERNAL
The user's guild-level permissions must include:
#### Get Permissions
* *No permissions required*
#### Create permissions
* `CREATE_EVENTS`
#### Modify/Delete Permissions
* If the event was created by the current user, either `CREATE_EVENTS` or `MANAGE_EVENTS`. Otherwise, `MANAGE_EVENTS`