v6 documentation is incomplete, want to contribute?

VRChat.community

API documentation, SDKs, and more
API Reference
Discord

Get Instance

Returns an instance. Please read Instances Tutorial for more information on Instances.

If an invalid instanceId is provided, this endpoint will simply return "null"!

Requests made through this page are proxied through an intermediary server due to Cross-Origin Resource Sharing restrictions.

GET
/instances/{worldId}:{instanceId}

Authorization

auth<token>

Auth Token via Cookie

In: cookie

Path Parameters

worldIdstring

Must be a valid world ID.

instanceIdstring

Must be a valid instance ID.

Response Body

  • hidden field is only present if InstanceType is hidden aka "Friends+", and is instance creator.
  • friends field is only present if InstanceType is friends aka "Friends", and is instance creator.
  • private field is only present if InstanceType is private aka "Invite" or "Invite+", and is instance creator.
activeboolean
Defaulttrue
ageGate?boolean
canRequestInviteboolean
Defaulttrue
capacityinteger
clientNumberstringDeprecated

Always returns "unknown".

Length1 <= length
contentSettingsInstanceContentSettings

Types of dynamic user content permitted in an instance

displayNamestring
fullboolean
Defaultfalse
gameServerVersion?integer
idInstanceID

InstanceID can be "offline" on User profiles if you are not friends with that user and "private" if you are friends and user is in private instance.

instanceIdstring
Length1 <= length
instancePersistenceEnabledstring
locationInstanceID

InstanceID can be "offline" on User profiles if you are not friends with that user and "private" if you are friends and user is in private instance.

n_usersinteger
namestring
Length1 <= length
ownerId?InstanceOwnerId

A groupId if the instance type is "group", null if instance type is public, or a userId otherwise

permanentboolean
Defaultfalse
photonRegionRegion

API/Photon region.

Default"us"
Value in"us" | "use" | "usw" | "usx" | "eu" | "jp" | "unknown"
platformsInstancePlatforms
playerPersistenceEnabledboolean
regionInstanceRegion

Instance region

Default"us"
Value in"us" | "use" | "eu" | "jp" | "unknown"
secureNamestring
Length1 <= length
shortName?string
Length1 <= length
tagsarray<Tag>

The tags array on Instances usually contain the language tags of the people in the instance.

typeInstanceType
Value in"public" | "hidden" | "friends" | "private" | "group"
worldIdWorldID

WorldID be "offline" on User profiles if you are not friends with that user.

hidden?UserID

A users unique ID, usually in the form of usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469. Legacy players can have old IDs in the form of 8JoV9XEdpo. The ID can never be changed.

friends?UserID

A users unique ID, usually in the form of usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469. Legacy players can have old IDs in the form of 8JoV9XEdpo. The ID can never be changed.

private?UserID

A users unique ID, usually in the form of usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469. Legacy players can have old IDs in the form of 8JoV9XEdpo. The ID can never be changed.

queueEnabledboolean
queueSizeinteger
recommendedCapacityinteger
roleRestricted?boolean
strictboolean
userCountinteger
worldWorld
users?array<LimitedUser>

The users field is present on instances created by the requesting user.

groupAccessType?GroupAccessType

Group access type when the instance type is "group"

Default"members"
Value in"public" | "plus" | "members"
hasCapacityForYou?boolean
nonce?string
closedAt?string
Format"date-time"
hardClose?boolean

Error response due to missing auth cookie.

error?Response
curl -X GET "https://api.vrchat.cloud/api/1/instances/string:string" \
  -H "auth: <token>"
fetch("https://api.vrchat.cloud/api/1/instances/string:string", {
  headers: {
    "auth": "<token>"
  }
})
package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {
  url := "https://api.vrchat.cloud/api/1/instances/string:string"

  req, _ := http.NewRequest("GET", url, nil)
  req.Header.Add("auth", "<token>")
  res, _ := http.DefaultClient.Do(req)
  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}
import requests

url = "https://api.vrchat.cloud/api/1/instances/string:string"

response = requests.request("GET", url, headers = {
  "auth": "<token>"
})

print(response.text)
{
  "active": true,
  "ageGate": true,
  "canRequestInvite": true,
  "capacity": 8,
  "clientNumber": "string",
  "contentSettings": {
    "drones": true,
    "emoji": true,
    "pedestals": true,
    "prints": true,
    "stickers": true
  },
  "displayName": "string",
  "full": false,
  "gameServerVersion": 0,
  "id": "12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)",
  "instanceId": "12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)",
  "instancePersistenceEnabled": "string",
  "location": "12345~hidden(usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469)~region(eu)~nonce(27e8414a-59a0-4f3d-af1f-f27557eb49a2)",
  "n_users": 6,
  "name": "12345",
  "ownerId": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469",
  "permanent": false,
  "photonRegion": "eu",
  "platforms": {
    "android": 1,
    "ios": 1,
    "standalonewindows": 5
  },
  "playerPersistenceEnabled": true,
  "region": "us",
  "secureName": "7eavhhng",
  "shortName": "02u7yz8j",
  "tags": [
    "show_social_rank",
    "language_eng",
    "language_jpn"
  ],
  "type": "hidden",
  "worldId": "wrld_ba913a96-fac4-4048-a062-9aa5db092812",
  "hidden": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469",
  "friends": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469",
  "private": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469",
  "queueEnabled": true,
  "queueSize": 6,
  "recommendedCapacity": 6,
  "roleRestricted": true,
  "strict": true,
  "userCount": 6,
  "world": {
    "authorId": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469",
    "authorName": "string",
    "capacity": 8,
    "recommendedCapacity": 4,
    "created_at": "2019-08-24T14:15:22Z",
    "defaultContentSettings": {
      "drones": true,
      "emoji": true,
      "pedestals": true,
      "prints": true,
      "stickers": true
    },
    "description": "string",
    "favorites": 12024,
    "featured": false,
    "heat": 5,
    "id": "wrld_ba913a96-fac4-4048-a062-9aa5db092812",
    "imageUrl": "string",
    "instances": [
      [
        null,
        null
      ]
    ],
    "labsPublicationDate": "none",
    "name": "string",
    "namespace": "string",
    "occupants": 47,
    "organization": "vrchat",
    "popularity": 8,
    "previewYoutubeId": "string",
    "privateOccupants": 1,
    "publicOccupants": 46,
    "publicationDate": "none",
    "releaseStatus": "public",
    "storeId": "esto_713b247d-2b5d-41a0-bba3-50db28dc1498",
    "tags": [
      "string"
    ],
    "thumbnailImageUrl": "string",
    "unityPackages": [
      {
        "id": "unp_52b12c39-4163-457d-a4a9-630e7aff1bff",
        "assetUrl": "https://api.vrchat.cloud/api/1/file/file_cd0caa7b-69ba-4715-8dfe-7d667a9d2537/65/file",
        "assetUrlObject": {},
        "assetVersion": 4,
        "created_at": "2020-09-10T06:13:27.777Z",
        "impostorizerVersion": "0.17.0",
        "performanceRating": "Excellent",
        "platform": "standalonewindows",
        "pluginUrl": "",
        "pluginUrlObject": {},
        "unitySortNumber": 20180414000,
        "unityVersion": "2022.3.6f1",
        "worldSignature": "AHiPAWerwCpeYrxDthF5TU2SdUWEWnm43UAn8PKRXlS8k8tVRQ==",
        "impostorUrl": "string",
        "scanStatus": "string",
        "variant": "string"
      }
    ],
    "updated_at": "2019-08-24T14:15:22Z",
    "urlList": [
      "string"
    ],
    "version": 68,
    "visits": 9988675,
    "udonProducts": [
      "prod_c1644b5b-3ca4-45b4-97c6-a2a0de70d469"
    ]
  },
  "users": [
    {
      "bio": "string",
      "bioLinks": [
        "string"
      ],
      "currentAvatarImageUrl": "https://api.vrchat.cloud/api/1/file/file_ae46d521-7281-4b38-b365-804b32a1d6a7/1/file",
      "currentAvatarThumbnailImageUrl": "https://api.vrchat.cloud/api/1/image/file_aae83ed9-d42d-4d72-9f4b-9f1e41ed17e1/1/256",
      "currentAvatarTags": [
        "string"
      ],
      "developerType": "none",
      "displayName": "string",
      "fallbackAvatar": "avtr_912d66a4-4714-43b8-8407-7de2cafbf55b",
      "id": "usr_c1644b5b-3ca4-45b4-97c6-a2a0de70d469",
      "isFriend": true,
      "last_platform": "standalonewindows",
      "last_login": "2019-08-24T14:15:22Z",
      "profilePicOverride": "string",
      "pronouns": "string",
      "status": "active",
      "statusDescription": "string",
      "tags": [
        "string"
      ],
      "userIcon": "string",
      "username": "string",
      "location": "string",
      "friendKey": "string"
    }
  ],
  "groupAccessType": "members",
  "hasCapacityForYou": true,
  "nonce": "string",
  "closedAt": "2019-08-24T14:15:22Z",
  "hardClose": true
}

{
  "error": {
    "message": "\"Missing Credentials\"",
    "status_code": 401
  }
}