> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST (/handles/query)

> POST (/handles/query)

Creates queries for session handles.

> **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](#ID4ET)
* [URI parameters](#ID4EDB)
* [Query string parameters](#ID4EQB)
* [HTTP status codes](#ID4EBF)
* [Request body](#ID4EIF)
* [Response body](#ID4ETF)

## Remarks

This HTTP/REST method creates queries for handle data only, without any session information. It can be wrapped by **Microsoft.Xbox.Services.Multiplayer.MultiplayerService.GetActivitiesForSocialGroupAsync**.

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 **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 **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

For all activities for a user's "favorites" social graph, the request body looks like this:

```cpp theme={null}
{
  "type": "activity",
  "scid": "B5B1F71F-A328-4371-89E0-C3AD222D0E92"  // optional filter on scid
  "owners": {
    "people": {
      "moniker": "favorites",
      "monikerXuid": "3210"
    }
  }
}

```

## Response body

The handles are retrieved as an array of handle structures, with a unique ID embedded in each structure.

```cpp theme={null}
{
  "results": [
    {
      "id": "11111111-ebe0-42da-885f-033860a818f6",
      "type": "activity",
      "version": 1,
      "sessionRef": {
        "scid": "8dfb0100-ebe0-42da-885f-033860a818f6",
        "templateName": "party",
        "name": "e3a836aeac6f4cbe9bcab985494d3175"
      },
      "titleId": "1234567",
      "ownerXuid": "3212",
      {
        "id": "11111111-ebe0-42da-885f-033860a818f7",
      "type": "activity",
      "version": 1,
      "sessionRef": {
         "scid": "8dfb0100-ebe0-42da-885f-033860a818f6",
        "templateName": "TitleStorageTestDefault",
        "name": "795fcaa7-8377-4281-bd7e-e86c12843632"
      },
      "titleId": "1234567",
      "ownerXuid": "3212",
    }
  }]
}

```

## See also

##### Parent

[/handles/query](https://docs.xbox.com/reference/live/rest/uri/sessiondirectory/uri-handlesquery.md)


## Related topics

- [/handles/query](https://docs.xbox.com/reference/live/rest/uri/sessiondirectory/uri-handlesquery.md)
- [POST (/handles/query?include=relatedInfo)](https://docs.xbox.com/reference/live/rest/uri/sessiondirectory/uri-handlesqueryincludepost.md)
- [Multiplayer session browse](https://docs.xbox.com/services/xbox-services/multiplayer/concepts/live-session-browse.md)
- [POST (/handles)](https://docs.xbox.com/reference/live/rest/uri/sessiondirectory/uri-handlespost.md)
- [POST /titles/{titleId}/activities/query](https://docs.xbox.com/reference/live/rest/uri/multiplayeractivity/swagger-uris/uri-ExternalGetActivityBatch.md)