---
sidebar_label: Stage Instance
---

# Stage Instance Resource

A _Stage Instance_ holds information about a live stage.

### Stage Instance Object

###### Stage Instance Structure

| Field                    | Type       | Description                                                                                                   |
|--------------------------|------------|---------------------------------------------------------------------------------------------------------------|
| id                       | snowflake  | The id of this Stage instance                                                                                 |
| guild_id                 | snowflake  | The guild id of the associated Stage channel                                                                  |
| channel_id               | snowflake  | The id of the associated Stage channel                                                                        |
| topic                    | string     | The topic of the Stage instance (1-120 characters)                                                            |
| privacy_level            | integer    | The [privacy level](/docs/resources/stage-instance#stage-instance-object-privacy-level) of the Stage instance |
| discoverable_disabled    | boolean    | Whether or not Stage Discovery is disabled (deprecated)                                                       |
| guild_scheduled_event_id | ?snowflake | The id of the scheduled event for this Stage instance                                                         |

###### Privacy Level

| Level      | Value | Description                                          |
|------------|-------|------------------------------------------------------|
| PUBLIC     | 1     | The Stage instance is visible publicly. (deprecated) |
| GUILD_ONLY | 2     | The Stage instance is visible to only guild members. |

###### Example Stage Instance

```json
{
  "id": "840647391636226060",
  "guild_id": "197038439483310086",
  "channel_id": "733488538393510049",
  "topic": "Testing Testing, 123",
  "privacy_level": 1,
  "discoverable_disabled": false,
  "guild_scheduled_event_id": "947656305244532806"
}
```

## Definitions

Below are some definitions related to stages.

- **Liveness:** A Stage channel is considered _live_ when there is an associated stage instance. Conversely, a Stage channel is _not live_ when there is no associated stage instance.
- **Speakers:** A participant of a Stage channel is a _speaker_ when their [voice state](/docs/resources/voice#voice-state-object)
  is not `suppress`ed, and has no `request_to_speak_timestamp`.
- **Moderators**: A member of the guild is a _moderator_ of a Stage channel if they have all of the following [permissions](/docs/topics/permissions#permissions):
  - `MANAGE_CHANNELS`
  - `MUTE_MEMBERS`
  - `MOVE_MEMBERS`
- **Topic**: This is the blurb that gets shown below the channel's name, among other places.
- **Public**: A Stage instance is public when it has a `privacy_level` of `PUBLIC`. While a guild has a public Stage instance:
  - Users in the Stage can have the Stage show in their [activities](/docs/events/gateway-events#presence).

## Auto Closing

When a Stage channel has no speakers for a certain period of time (on the order of minutes), the Stage instance will be automatically deleted.

## Create Stage Instance
<Route method="POST">/stage-instances</Route>

Creates a new Stage instance associated to a Stage channel. Returns that [Stage instance](/docs/resources/stage-instance#stage-instance-object-stage-instance-structure). Fires a [Stage Instance Create](/docs/events/gateway-events#stage-instance-create) Gateway event.

Requires the user to be a moderator of the Stage channel.

:::info
This endpoint supports the `X-Audit-Log-Reason` header.
:::

###### JSON Params

| Field                       | Type      | Description                                                                                                                        |
|-----------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------|
| channel_id                  | snowflake | The id of the Stage channel                                                                                                        |
| topic                       | string    | The topic of the Stage instance (1-120 characters)                                                                                 |
| privacy_level?              | integer   | The [privacy level](/docs/resources/stage-instance#stage-instance-object-privacy-level) of the Stage instance (default GUILD_ONLY) |
| send_start_notification? \* | boolean   | Notify @everyone that a Stage instance has started                                                                                 |
| guild_scheduled_event_id?   | snowflake | The guild scheduled event associated with this Stage instance                                                                      |

\* The stage moderator must have the `MENTION_EVERYONE` permission for this notification to be sent.

## Get Stage Instance
<Route method="GET">/stage-instances/[\{channel.id\}](/docs/resources/channel#channel-object)</Route>

Gets the stage instance associated with the Stage channel, if it exists.

## Modify Stage Instance
<Route method="PATCH">/stage-instances/[\{channel.id\}](/docs/resources/channel#channel-object)</Route>

Updates fields of an existing Stage instance. Returns the updated [Stage instance](/docs/resources/stage-instance#stage-instance-object-stage-instance-structure). Fires a [Stage Instance Update](/docs/events/gateway-events#stage-instance-update) Gateway event.

Requires the user to be a moderator of the Stage channel.

:::info
This endpoint supports the `X-Audit-Log-Reason` header.
:::

###### JSON Params

| Field          | Type    | Description                                                                                                   |
|----------------|---------|---------------------------------------------------------------------------------------------------------------|
| topic?         | string  | The topic of the Stage instance (1-120 characters)                                                            |
| privacy_level? | integer | The [privacy level](/docs/resources/stage-instance#stage-instance-object-privacy-level) of the Stage instance |

## Delete Stage Instance
<Route method="DELETE">/stage-instances/[\{channel.id\}](/docs/resources/channel#channel-object)</Route>

Deletes the Stage instance. Returns `204 No Content`. Fires a [Stage Instance Delete](/docs/events/gateway-events#stage-instance-delete) Gateway event.

Requires the user to be a moderator of the Stage channel.

:::info
This endpoint supports the `X-Audit-Log-Reason` header.
:::