Skip to main content

​
POST (/handles/query?include=relatedInfo)

Creates queries for session handles that include related session information.
Important:
This method is used by the 2015 Multiplayer and applies only to that multiplayer version and later. It is intended for use with template contract 104/105 or later, and requires a header element of X-Xbl-Contract-Version: 104/105 or later on every request.

​
Remarks

This HTTP/REST method creates queries for handle data with session information specified in the “include” query string. The query string value is designed to be extensible to support future query options, supporting a comma-delimited list, for example, “?include=relatedInfo,session”. The POST method can be wrapped by Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForUsersAsync. The type field in the request body for this method must be set to “activity”. The items in the response body map directly to the properties of the Microsoft.Xbox.Services.Multiplayer.MultiplayerActivityDetails.

​
URI parameters

​
Query string parameters

A query can be modified using the query string parameters in the next table. | Parameter| Type| Description| | --- | --- | --- | --- | | keyword| string| A keyword, for example, “foo”, that must be found in sessions or templates if they are to be retrieved. | | xuid| 64-bit unsigned integer| The XBOX user ID, for example, “123”, for sessions to include in the query. By default, the user must be active in the session for it to be included. | | reservations| boolean| True to include sessions for which the user is set as a reserved player but has not joined to become an active player. This parameter is only used when querying your own sessions, or when querying a specific user’s sessions server-to-server. | | inactive| boolean| True to include sessions that the user has accepted but is not actively playing. Sessions in which the user is “ready” but not “active” count as inactive. | | private| boolean| True to include private sessions. This parameter is only used when querying your own sessions, or when querying a specific user’s sessions server-to-server. | | visibility| string| Visibility state for the sessions. Possible values are defined by the Microsoft.Xbox.Services.Multiplayer.MultiplayerSessionVisibility. If this parameter is set to “open”, the query should include only open sessions. If it is set to “private”, the private parameter must be set to true. | | version| 32-bit signed integer| The maximum session version that should be included. For example, a value of 2 specifies that only sessions with a major session version of 2 or less should be included. The version number must be less than or equal to the request’s contract version mod 100. | | take| 32-bit signed integer| The maximum number of sessions to retrieve. This number must be between 0 and 100. | Setting either private or reservations to true requires server-level access to the session. Alternatively, these settings require the caller’s XUID claim to match the XUID filter in the URI. Otherwise, the HTTP/403 status code is returned, whether or not any such sessions actually exist.

​
HTTP status codes

The service returns an HTTP status code as it applies to MPSD.

​
Request body

​
Sample request

To get all activities for a user’s “favorites” social graph, the POST body looks like this:

​
Response body

The results are returned as an array of handle structures, with a unique ID embedded in each handle. The specific session information is returned in the relatedInfo object. Note that this information is not returned for the regular POST method on this URI.

​
Sample response

​
See also

Parent
/handles/query
Last modified on August 20, 2026

Related topics

GDK Commerce Systems OverviewPAGE · Pre-planning and post-event accessibility checklistsXR-014 Player Data and Personal InformationStore listing for titles on XBOX devicesMultiplayer Session Directory overview