Skip to content

Get Session By Id

GET
/session/v1/session/{session_id}

Get Session by ID. This request will return limited results for non-members of the session, such as excluding info for how to connect to the instance. Elevated permissions can bypass that restriction

Required Permissions:

  • For any player (including themselves) any of: session:*, session:read:any, session:read:self

Required Session Permissions: None for limited results. SessionPermissions.active_in_session to get complete results for users who do not have the session:read:any auth permission

Authorizations

Parameters

Path Parameters

session_id
required
string
>= 1 characters <= 128 characters

Query Parameters

refresh_ttl
boolean
default: true

Header Parameters

if-none-match

If you provide the ETag that matches the current ETag for this resource, a 304 response will be returned - indicating that the resource has not changed.

string

If you provide the ETag that matches the current ETag for this resource, a 304 response will be returned - indicating that the resource has not changed.

Responses

200

Successful Response

A session resource

object
type
required

Template type

string
session_id
required

Unique ID for this session within its type

string
>= 1 characters <= 128 characters
instance

Info about the current active instance for the session

object
allocation_id

Allocation ID for instance that’s been spun up

string
>= 1 characters <= 128 characters
instance_id
required

Unique ID for the host/session relationship

string
>= 1 characters <= 128 characters
host_type
required

Type of the host

string
Allowed values: dedicated player
host_player_id

Player ID of the host, if the host type is player

integer
host_player_uuid

Player UUID of the host, if the host type is player

string format: uuid
host_dedicated_process_id

Unique ID for the process that is running this instance

string
host_dedicated_server_id

Unique ID for the machine running the instance

string
join_status
required

Is the instance joinable at this time?

string
Allowed values: requested allocated pending joinable unjoinable closed
join_params

Parameters to join the instance

object
public_conn_str
required

Public connection string for instance

string
private_conn_str
required

Private connection string for instance

string
custom_data

Custom data to join a instance

object
key
additional properties
string
>= 1 characters <= 4096 characters
instance_startup_params

Parameters used by the host to startup. For UE5 this will contain the map and gamemode

object
map
required

Name of the map for the instance to spawn with

string
mode

Game mode for the instance to spawn in

string
misc_params
required

Additional commandline parameters for the instance

string
custom_data

Custom data to pass through to the instance

object
key
additional properties
string
>= 1 characters <= 4096 characters
version

Product Client Version number. Used for compatibility checking with players

string format: semver
21.3.15-beta+12345
created
required

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time
custom_data

Instance-defined custom data

object
key
additional properties
string
>= 1 characters <= 4096 characters
instance_health

The current status of the instance

string
Allowed values: healthy unhealthy degraded unknown
match_making_profile_id

The profile id that this instance was spawned from

string
>= 1 characters <= 128 characters
match

DEPRECATED Info about the current match in the instance

object
match_id
required

Unique ID

string
created
required

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time
custom_data

Instance-defined custom data

object
key
additional properties
string
>= 1 characters <= 4096 characters
ticket_ids

List of tickets that were assigned to this match if created by matchmaking

Array<string>
default:
matchmaking_results

Info about the matchmaking results that resulted in this session

object
match_making_id
required

Unique ID

string
created
required

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time
custom_data

MMF defined custom data

object
key
additional properties
string
>= 1 characters <= 4096 characters
ticket_ids

List of tickets that were assigned to this match if created by matchmaking

Array<string>
default:
tickets_assigned

Whether or not the tickets from these results have been assigned

boolean
matchmaking

Info about the matchmaking state of the session, if it is in the process of matchmaking

object
ticket_id
required

Unique ID for this attempt at matchmaking

string
custom_data

Session-defined custom data

object
key
additional properties
string
>= 1 characters <= 4096 characters
queue_id

Unique ID for the joined queue

string
>= 1 characters <= 128 characters
backfill

Info about the open-match backfill object for the session

object
backfill_id
required

Unique ID for the backfill object

string
>= 1 characters
extensions

Optional additional extensions used when acknowledging backfill requests

object
key
additional properties
string
>= 1 characters <= 4096 characters
browser

Info about the browser state of the session

object
custom_data

Custom data with the listing of the instance in the Session browser

object
key
additional properties
string
>= 1 characters <= 4096 characters
joinable
required

Is this session freely joinable by players without an invite?

boolean
teams
required

List of teams of players currently in the session

Array<object>

A team of SessionPlayers in a session

object
players
required

Players currently on this team

Array<object>

A player resource in a session

object
player_id

Legacy id for this player

integer
player_uuid
required

UUID for this player

string format: uuid
status
required

Status of the player in the session

string
Allowed values: leader member invited reserved
inviting_player_uuid

UUID of the player who sent this players invite, if any

string format: uuid
source_session_id

The UUID of the session that this player was invited from

string
>= 1 characters <= 128 characters
custom_data

Player-defined custom data

object
key
additional properties
string
>= 1 characters <= 4096 characters
version

Product Client Version number. Used for compatibility checking with other players and instances

string format: semver
21.3.15-beta+12345
client_settings

Which input type and platform the client is using

object
platform_id

DEPRECATED. Use ‘platform’ instead. Id for which platform this client is on. ID will be ignored if ‘platform’ is given. At least one of the two is required

integer
platform

Which platform this client is on. If one is not provided, will get the platform from the ‘platform_id’. At least one of the two is required

string
Allowed values: Anon Basic XboxLive PSN NintendoNAID NintendoSwitch NintendoPPID Google GooglePlay Apple Epic Steam Amazon Twitch RallyHere LegacyName
input
required

Which input type this client is using

string
Allowed values: keyboardandmouse gamepad touch
crossplay_preferences

Client’s desired crossplay settings to determine which other clients it can play with. If not defined, assumed to be as permissive as possible

object
permitted_platform
required

The platform type that the client is allowed to play with (any, xbox-like only, playstation-like only etc.)

string
Allowed values: desired_platforms_any desired_platforms_xboxlike desired_platforms_playstationlike
permitted_input
required

The input type that the client is allowed to play with (keyboard and mouse, gamepad, touch input etc.)

string
Allowed values: desired_inputs_any desired_inputs_keyboardandmouse desired_inputs_gamepad desired_inputs_touch
invited

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time
joined

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time
max_size
required

Maximum number of players allowed on this team

integer
>= 1 <= 100
team_id

Which team this is

integer
ticket_ids

Matchmaking tickets that were assigned to this team

Array<string>
custom_data

Custom data about this team

object
key
additional properties
string
>= 1 characters <= 4096 characters
platform_session

Child Platform Sessions for this session. A player joining one of the child platform sessions implicitly joins the parent session

Array<object>
default:

A platform session resource in a RallyHere session

object
platform
required

Platform that this session is for

string
Allowed values: Anon Basic XboxLive PSN NintendoNAID NintendoSwitch NintendoPPID Google GooglePlay Apple Epic Steam Amazon Twitch RallyHere LegacyName
platform_session_type
required

Platform-Specific Identifier for the Platform’s template

string
>= 1 characters <= 128 characters
platform_session_id_base64
required

Platform session’s unique identifier

string
>= 1 characters <= 4096 characters
players
required

DEPRECATED. PlatformSessions no longer keep tracking of players. Players in the platform session

Array<object>

A platform player resource in a platform session

object
player_id

Player ID representing the current player

integer
player_uuid
required

Player UUID representing the current player

string format: uuid
leader

Is this player the leader of the platform session? When setting up the parent session, if all players are from the same platform session, leadership is coordinated

boolean
custom_data

Product defined custom data fields about the platform session

object
key
additional properties
string
>= 1 characters <= 4096 characters
custom_data

Leader Player or instance defined custom data about this session

object
key
additional properties
string
>= 1 characters <= 4096 characters
created
required

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time
region_id

Preferred region for the instance and match to take place in

string
>= 1 characters <= 128 characters
created_by_matchmaking

Flag of whether or not this session was created by matchmaking or not

boolean

Headers

ETag
string

Used to identify this version of the content. Provide with a get request to avoid downloading the same data multiple times.

403

Forbidden

object
auth_success
boolean
default: true
error_code
required
string
desc
required
string

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string